Data Access Routines User Guide

Data Access Routines User Guide

Version 11.6

pdms1160/Data Access Routines User Guide issue 070904

PLEASE NOTE: AVEVA Solutions has a policy of continuing product development: therefore, the information contained in this document may be subject to change without notice. AVEVA SOLUTIONS MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS DOCUMENT, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. While every effort has been made to verify the accuracy of this document, AVEVA Solutions shall not be liable for errors contained herein or direct, indirect, special, incidental or consequential damages in connection with the furnishing, performance or use of this material. This manual provides documentation relating to products to which you may not have access or which may not be licensed to you. For further information on which Products are licensed to you please refer to your licence conditions.

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

For details of AVEVA's worldwide sales and support offices, see our website at http://www.aveva.com

Aveva Solutions Ltd, High Cross, Madingley Road, Cambridge CB3 0HB, UK

Contents

1 Introduction .................................................................................................. 1-1 1.1 Scope of Data Access Routines .................................................................................1-1 1.2 Who Can Use Data Access Routines?.......................................................................1-1 1.3 Interfacing to 'C/C++' Programs ...............................................................................1-2 1.4 How To Use This Manual .........................................................................................1-2 1.5 Use of Other PDMS Manuals ...................................................................................1-3 1.6 Changes at PDMS Mk11...........................................................................................1-3 2 Programming Techniques ........................................................................... 2-1 2.1 FORTRAN 77.............................................................................................................2-1 2.2 Declarations...............................................................................................................2-1 2.3 CHARACTER Handling............................................................................................2-2 2.4 Subroutine and Common Block Naming..................................................................2-4 2.5 Error Handling ..........................................................................................................2-4 3 Basic Concepts of PDMS Data Access....................................................... 3-1 3.1 PDMS Database Organisation..................................................................................3-1 3.2 PDMS Database Security..........................................................................................3-1 3.3 Current Element .......................................................................................................3-1 3.4 User-Defined Attributes............................................................................................3-2 3.5 Dynamic Array Attributes ........................................................................................3-2 3.6 Monitoring .................................................................................................................3-2 3.7 Site File......................................................................................................................3-3 3.8 Multibyte Text ...........................................................................................................3-3 4 Use of Data Access Routines...................................................................... 4-1 4.1 Introduction ...............................................................................................................4-1 4.2 Example 1 ..................................................................................................................4-1 4.3 Example 2 ..................................................................................................................4-7 5 Subroutine Specifications ........................................................................... 5-1 5.1 Introduction ...............................................................................................................5-1 5.2 Subroutine Summaries .............................................................................................5-3

5.2.1 Initialisation Routines, D3Ixxx .......................................................................5-3 5.2.2 Navigation Routines, D3Mxxx.........................................................................5-3 5.2.3 Read Routines, D3Rxxx ...................................................................................5-4 5.2.4 Error Handling Routines, D3Exxx ..................................................................5-7 5.2.5 Utility Routines, D3Uxxx ................................................................................5-7 5.2.6 Termination Routines, D3Fxxx .......................................................................5-8 5.2.7 General Utility Routines, D3Uxxx ..................................................................5-8

5.3 Detailed Subroutine Specifications ..........................................................................5-9

VANTAGE Plant Design Data Access Routines i User Guide Version 11.6

Introduction

6 Version Control ............................................................................................ 6-1 6.1 DARs Version Numbering........................................................................................ 6-1 6.2 Compatibility of Databases and DARs .................................................................... 6-1 6.3 Determination of Version Number .......................................................................... 6-2 A DARs Library Details ...................................................................................A-1 A.1 Software Issued with DARs.....................................................................................A-1 A.2 File Handling ...........................................................................................................A-2 A.3 Application Program Compilation and Linking .....................................................A-3 A.4 Program Running and Debugging ..........................................................................A-4 A.5 Acceptance Test Program ........................................................................................A-4 A.6 Re-Linking Application Programs ..........................................................................A-5 B Running Examples.......................................................................................B-1

C Error Codes and Messages.........................................................................C-1

D Auxiliary Subroutine Library.......................................................................D-1 D.1 Introduction.............................................................................................................. D-1 D.2 List of Subroutines................................................................................................... D-1 D.3 Subroutine Outline Specifications ......................................................................... D-3 E Multibyte Text Handling............................................................................... E-1

F C/C++ Library ............................................................................................. F-1 F.1 Software Issued with DARs C/C++ Library..........................................................F-1 F.2 Application Program Compilation and Linking.....................................................F-1 F.3 Program Running and Debugging ..........................................................................F-1 F.4 Acceptance Test Program........................................................................................F-1 F.5 Compilation and Linking Script .............................................................................F-2 F.6 'C/C++' Header Files ................................................................................................F-3 F.7 Example 'C' Program .............................................................................................F-12 F.8 'C/C++' Interface Principles...................................................................................F-20 F.9 Use of System Calls in DARs Programs ...............................................................F-21

ii VANTAGE Plant Design Data Access Routines User Guide

Version 11.6

1 Introduction

1.1 Scope of Data Access Routines

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

1.2 Who Can Use Data Access Routines?

Within this manual, the term user refers to a user of a PDMS DARs application program. He will of necessity also be a PDMS user. The term programmer refers to the programmer who calls PDMS DARs routines in an application program.

VANTAGE Plant Design Data Access Routines 1-1 User Guide Version 11.6

Introduction

The programmer is expected to be familiar with PDMS and proficient at FORTRAN 77 programming. The user does not need any programming knowledge, providing the programmer makes his program sufficiently user-friendly. Aveva Solutions Ltd can provide consultancy services to assist customers in the preparation of applications programs. The experienced programmer, however, will find DARs no more difficult to use than other well-written library packages. To assist the programmer in his program development, a monitor option may be selected to obtain information on entry to and exit from each data access routine. A PDMS user identification and password will be needed to use an application program and the privilege of the user will be checked before any action is performed.

1.3 Interfacing to 'C/C++' Programs

A DARs 'C/C++' interface is included in the PDMS DARs release for all platforms. Details are presented in Appendix F for each of the supported machine types.

1.4 How To Use This Manual

This manual is provided more for the use of the DARs programmer than for the user of DARs applications programs. Sections 1 to 3 of this manual provide the programmer with an introduction to the philosophy involved in PDMS data access and some of the programming techniques that may be necessary. Section 4 gives examples of the use of DARs in several simple applications. FORTRAN source files and terminal output are given for these examples. Compilation, loading and running details are provided in Appendix B for each of the supported machine types. More detailed machine-specific information is presented in Appendices Error! Reference source not found., B and F, together with details of the 'C/C++' interface. Section 5 is a reference section, providing both summaries and detailed specifications for all data access routines. The detailed specifications follow a standard format. In particular, a convention of underlining return arguments has been adopted. Each routine specification gives

1-2 VANTAGE Plant Design Data Access Routines User Guide

Version 11.6

Introduction

detailed definitions of all arguments and lists the possible error conditions that can arise. Section 6 gives details of version control mechanisms. Appendix C provides a list of error messages for easy reference. Appendix D gives brief details of an auxiliary subroutine library supplied with PDMS DARs which contains FORTRAN subroutines that DARs programmers may find useful as they stand or as a template for their own routines.

1.5 Use of Other PDMS Manuals

Part 3 of the VANTAGE PDMS DESIGN Reference Manual for gives details of PDMS elements and their attributes. A comprehensive list of all PDMS attributes and pseudo-attributes is given in the Plant Design Software Customisation Reference Manual.

1.6 Changes at PDMS Mk11

As a result of the new version of DABACON at PDMS Mk11 and other significant changes introduced with this major version, there are several aspects of PDMS Mk11 DARs that are not upwards compatible from Mk10. These changes are noted as footnotes in Section 5, summarised as follows: PDMS words can now be of length 6 (previously maximum of four) PDMS words are now stored as integers in the PDMS database

(previously real numbers). As a result, subroutine D3UDEH word argument is now INTEGER instead of REAL.

Many input arguments were previously truncated to four characters. At 11, DARs will accept element types and attribute names in the same form as they are recognised by PDMS.

Routines handling dates now accept or return a four-digit year.


Introduction


Version 11.6

2 Programming Techniques

2.1 FORTRAN 77

PDMS DARs are written in FORTRAN 77 and can be called from any FORTRAN 77 program or from any other program that can call ANSI standard FORTRAN 77 subroutines. It is not within the scope of this manual to explain FORTRAN 77 programming methods. If necessary, the following text book is recommended:

Title: Programming in Standard Fortran 77 Authors: A. Balfour and D.H. Marwick Publisher: Heinemann Educational Books, 1982 Hardback: ISBN 0 435 77485 9 Paperback: ISBN 0 435 77486 7

If the programmer does not wish to pass character strings into the application program or can convert to and from hollerith constants or ASCII integer arrays, it would be possible to interface PDMS DARs to a FORTRAN 66 application program via a neutral interface.

2.2 Declarations

The subroutine summaries define the argument declarations that are used within the DARs. The following naming convention has been adopted in the subroutine specifications:

CHARACTER CD3xxx INTEGER ID3xxx REAL RD3xxx LOGICAL LD3xxx


Programming Techniques

Character and logical arguments must be explicitly declared in calling routines. Integer and real arguments comply with the default FORTRAN 77 naming convention and need not be declared. Wherever assumed size arrays or character strings are used e.g. INTEGER ID3XYZ(*)

CHARACTER*(*) CD3XYZ the programmer must provide the appropriate explicit declaration in the application program. Functions are avoided in PDMS DARs but some general utility functions are provided. The calling routine must make the following declarations where these functions are used:

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').


Version 11.6


Programmers should be aware that an assignment such as: CHARACTER*10 CD3XYZ . . CD3XYZ = 'ABC'

will result in a character string 'ABC '; that is 'ABC' followed by seven blanks. This is true even if CD3XYZ previously contained more than three non-blank characters. Whilst the string 'ABC ' is interpreted the same as 'ABC', the string ' ABC' will not be. If the programmer wishes to know the significant length of a returned string (e.g. the significant length of 'ABC ' is 3), he may use the general utility function D3ULEN. e.g. EXTERNAL D3xxxx, D3ULEN

INTEGER 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 Subroutine and Common Block Naming

PDMS DARs have adopted a simple naming convention for subroutines and common blocks. All names begin with the prefix 'D3'. DARs programmers should therefore avoid the use of subroutine and common block names starting with 'D3'. They would also be wise to avoid 'D2' if they expect to use PEGS DARs. If DARs programmers experience difficulty with this aspect of interfacing to PDMS DARs, they should bring their problem to the attention of Aveva. Problems should only arise with interfaces to established programs or with programs using other subroutine libraries.

2.5 Error Handling

The DARs routines trap user input argument errors and cases where return character arguments are too short for the data being returned. The way in which such errors are handled varies according to the routine and is detailed in the 'Subroutine Specifications'. Many other potential errors are detected by the routines in the course of execution. All error conditions are communicated to the calling program through a return status code argument (always named ID3ERR in the subroutine specifications). A zero status code signifies successful execution; a positive value indicates an error condition. Each subroutine specification lists the status codes applicable to it and a full list is provided in Appendix C. Whenever an error condition is returned, the DARs set an internal error flag. This prevents entry into the next DARs routine (unless it is D3FIN, D3EMSG, D3ERST or D3UMON). The purpose of this action is to make the error obvious to the programmer (or to the user) and to prevent subsequent return of useless data. When such a failure occurs, helpful information concerning the source of the error is output to the screen. The programmer can obtain even more information by setting the monitor flag at an appropriate point. In some circumstances, the programmer deliberately creates an error condition. This is a convenient way to terminate a loop. Routine D3ERST is provided to allow the programmer to reset the internal error flag in such a situation. Thus, the internal error flag is a device to trap errors not expected by the programmer.


Version 11.6


The following extract from D3QMEM in the auxiliary routine library illustrates use of these principles. The status code returned by a routine can be converted into a message by a call to D3EMSG. C Move 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

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.


Version 11.6

3 Basic Concepts of PDMS Data Access

3.1 PDMS Database Organisation

The VANTAGE PDMS ADMIN Reference Manual provides an overview of 'The Project Control Administration System' in terms of database organisation for a project and the grouping of databases in MDBs.

3.2 PDMS Database Security

The data access initialisation routine D3INIT requires a valid project name and a username and password valid for that project. If invalid values are passed, then an error code is returned and the PDMS project is closed down. The MDB selection routine D3MMDB, called after a successful initialisation, requires a valid MDB name for the selected project. If the MDB is not found, the user is allowed further attempts (since this may be a deliberate programming strategy). Any other error condition (e.g. database in use) results in close down of the project. Since access to all databases is read only, there is no threat to the integrity of the PDMS project databases in the event of either machine or program failure.

3.3 Current Element

The navigation routines follow the current PDMS navigation techniques and standards. The PDMS concept of 'current element' is thus maintained. All data attributes are retrieved by first moving to the required element using the navigation routines, and then calling the appropriate attribute retrieval routine.


Basic Concepts of PDMS Data Access

3.4 User-Defined Attributes

The routines that retrieve attributes may be used for both system-defined and user-defined attributes (UDAs). As with PDMS, DARs routines identify UDAs by a leading ':' character in the UDA name.

3.5 Dynamic Array Attributes

At PDMS Mk10, the concept of dynamic array attributes was introduced. In earlier versions of PDMS all array attributes were of fixed size (e.g. PARA was a real array of size 3, 4, 5, 6, 7, 10, 15 or 30). This was designed to prevent wasteful use of database space, since any array positions not used are present in the database. With dynamic arrays, the user may define data for any number of array positions up to a maximum (typically 200). This is only of particular use where the number of array positions is not fixed. For example, attributes POS and ORI, arrays of size 3, will never need less than three values. Where dynamic arrays are defined and no values are set, PDMS DARs will return the error condition 'Attribute not found'. The same technique is also applied to text attributes. In earlier versions of PDMS all text attributes were of fixed length (e.g. STEX could be of length 15, 30, 45, 60, 75, 90, 105 or 120). With dynamic text, the user may define text of any length up to a maximum (typically 120). Where dynamic text is defined and no text has been provided, DARs will return the error condition Attribute unset.

3.6 Monitoring

The monitoring facility enables the programmer to set the level of information displayed by the Data Access routines. It is set by an argument passed to the initialisation routine D3INIT and can be reset at any point by a call to D3UMON. If the monitor option FULL is selected, then every time a data access routine is called, the name of the routine is displayed along with the values of all the input arguments, and on exit the returned argument values are displayed, together with all warning and error conditions encountered. Alternatively, the programmer may set the monitor level to OFF. In this case, he can use the routine D3EMSG to display error messages as he wishes. Note that even if the monitor level is set to OFF, some important low level messages will still be displayed on the screen.


Version 11.6


3.7 Site File

PDMS DARs operate a sitefile checking procedure in the same manner as PDMS. A DARs program user is included in the count of PDMS users. A PDMS DARs application program will not continue to execute if a fatal sitefile error is encountered. Sitefile warning messages and fatal error messages will be output to the terminal.

3.8 Multibyte Text

If a PDMS project has been identified as multibyte (PROJECT MBCHARSET in the ADMIN module), it is possible for users to enter multibyte element names and attributes in some PDMS modules. This allows Far Eastern users to enter Kanji text, which is stored in PDMS as multibyte text (two bytes per Kanji character). This also applies to the Chinese alphabet. Kanji and Chinese text can be input to or returned by DARs routines. The method of interpreting multibyte names and text accessed through DARs is detailed in Appendix E.




Version 11.6

Use of Data Access Routines

4 Use of Data Access Routines

4.1 Introduction

The use of data access routines is best illustrated by reference to some simple examples. The examples used in this section are based on the PDMS project used in the acceptance test. Details in this section are applicable to any machine type. Where the examples use a PRINT (or list-directed WRITE) statement, programmers should note that the default format obtained is dependent on the compiler. Further, some compilers skip column 1 whether outputting to terminal or file. This is not the case when a FORMAT specifier is used with a WRITE statement, where the programmer can control the placement of characters, including the use of column 1. In this situation, the output should not be dependent on the compiler. The output for these examples is therefore system-dependent in some minor respects (e.g. spacing of numbers and number of decimal places). The output shown in this section is typical. Example 1 is a simple example, involving navigation to the last flange in the first branch of a named pipe. Example 2 is a longer example, involving calls to several of the auxiliary routines. FORTRAN source files for the two examples are included with a release of data access routines.

4.2 Example 1

The FORTRAN 77 code for the application program is as follows: PROGRAM EXMPL1 C Application main program C Essential type declarations CHARACTER*50 SPCREF, CATREF C Can declare CD3MSG CHAR*1 if not using it CHARACTER*1 CD3MSG



CHARACTER*6 CD3WOR, WORDS(100) REAL PARAMS(100) C Optional EXTERNAL declarations EXTERNAL D3INIT, D3MMDB, D3MNAM, D3MNUM, D3MREL, D3RNAM EXTERNAL D3RRA, D3RWA, D3EMSG, D3FIN, D3FEND, D3UMON, D3UDEH C 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 DO 100 I=1, ID3NOU


Version 11.6


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 CALL D3FEND END Compilation, loading and running instructions are detailed in Appendix 0.



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 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 Project not found 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 11.6


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/MAX_DB_LENGTH_31_AFTER_THESLASH Read CATA CATAL/C Read PROP PIPE/PROP Read DESI PIPE/DR Read DICT PIPE/DICT1 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 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:


Version 11.6


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: 8 Element 1 100.0000 Element 2 254.0000 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 Appendix 0) may be studied in conjunction with the bare application code: C------------------- PROGRAM EXMPL2 C------------------- LOGICAL PROJIN, MDBIN C 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 C Exit 12345 CONTINUE CALL D3FIN( IFINDM ) CALL D3FEND END C------------------------------ LOGICAL FUNCTION PROJIN() C------------------------------ CHARACTER*1 TEXT C Optional declarations INTEGER IERR EXTERNAL D3INIT, D3EMSG PRINT*, 'Enter project'


Version 11.6


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 TEXT C Optional declarations INTEGER IERR EXTERNAL D3MMDB, D3EMSG PRINT*, 'Select MDB' CALL D3MMDB( '/PLANT', ' ', IERR ) MDBIN = IERR.EQ.0 CALL D3EMSG( IERR, .TRUE., TEXT ) RETURN END C---------------------- SUBROUTINE DECCHK C---------------------- CHARACTER*50 TEXT, NAMES(100) CHARACTER*6 TYPES(100), TYPE, HCON, TCON, FLOW, 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), HDIR(3), TPOS(3), TDIR(3), POS(9) REAL ORI(3), ANGL C Optional declarations INTEGER ISIZ, IERR, LEAV, IDISP REAL XLEN, YLEN, ZLEN, HEIG, RADI REAL BORE, HBOR, TBOR, TEMP, PRES EXTERNAL D3MNAM, D3MNUM, D3UMON, D3RPAT, D3MREL, D3RORL EXTERNAL D3RPRL, D3EMSG EXTERNAL D3QMEM, D3QSIT, D3XLEN, D3QZON, D3QPIP, D3QBRA EXTERNAL D3QTEE, D3QELB, D3QEQU, D3QBOX, D3QNOZ, D3MMDB 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


Version 11.6


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 ) 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 /EQU got ', NAME(:D3XLEN(NAME)) 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, + 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 /250-B-5 got ', NAME(:D3XLEN(NAME)) 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 /250-B-5/1 got ',NAME(:D3XLEN(NAME))


Version 11.6


GOTO 12345 ENDIF C Branch PPoints with Monitoring CALL D3UMON( 'FULL' ) CALL D3RPAT( 'PH', '/EQ3', POS(1), POS(4), BORE, HCON, IERR ) 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' ) 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 /1501B got ', NAME(:D3XLEN(NAME)) 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 )


Version 11.6


IF ( IERR .NE. 0 ) GOTO 12345 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, CREF, CATR, ANGL, HEIG, RADI, DUTY, + ISPE, IERR ) 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 display flag (first argument of D3Q routines) to 2. Enter project



PDMS DARs 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 Members of SITE /EQU 1 ZONE /EQ1 2 ZONE /EQ2 3 ZONE /EQ3 Exiting D3QMEM


Version 11.6


Entering D3QSIT Attributes of SITE /EQU Entering D3QCMA TYPE SITE NAME /EQU OWNE /* LOCK F Exiting D3QCMA POS 0.0000000E+00 0.0000000E+00 0.0000000E+00 ORI 0.0000000E+00 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 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+00 0.0000000E+00 100000.0 ORI 0.0000000E+00 0.0000000E+00 0.0000000E+00 PSPE =0/0 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


Version 11.6


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 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 /250-B-5/1 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


Version 11.6


EREC 0 DSCO Unset PTSP Unset INSC Unset SAFC 0 Exiting D3QBPA LHEA T LTAI T DETA F LSTR F HBOR 200.0000 TBOR 200.0000 HCON FGD TCON FGD FLOW Unset HSTU /A3B/200P HREF /1301-S2 TREF /1301-S3 HPOS -319150.0 297760.0 2105.000 HDIR 0.0000000E+00 0.0000000E+00 1.000000 TPOS -319150.0 302640.0 2105.000 TDIR 0.0000000E+00 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 U 2105 Direction unit vector E 0 N 0 U 1 Bore 200 Connection type FGD



Error code 0 Entering subroutine D3RPAT Input arguments: PPoint number ptail Coordinate system worl Exiting subroutine D3RPAT Output arguments: Position E -319150 N 302640 U 102105 Direction unit vector E 0 N 0 U 1 Bore 200 Connection type FGD Error code 0 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+00 0.0000000E+00 0.0000000E+00 SPRE /A3B/250T LSTU =0/0 BUIL F SHOP F ORIFL T POSFL T ISPE =0/0


Version 11.6


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 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 U 103886 Direction unit vector E -1 N 0 U 0 Bore 200 Connection type BWD Error code 0 Entering subroutine D3RPAT Input arguments: PPoint number P2 Coordinate system WORL Exiting subroutine D3RPAT Output arguments: Position E -318315 N 298064 U 103886 Direction unit vector E 0 N 1 U 0 Bore 200 Connection type BWD Error code 0 Entering subroutine D3UMON Input arguments: 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


Version 11.6


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+00 0.0000000E+00 180.0000 ISPE =0/0 Exiting D3QEQU Exiting subroutine D3UMON Entering subroutine D3RORL Input arguments: Coordinate system owne Exiting subroutine D3RORL Output arguments: Orientation unit vectors X axis E -1 N 0 U 0 Y axis E 0 N -1 U 0 Z axis E 0 N 0 U 1 Error code 0 Entering subroutine D3RORL Input arguments:



Coordinate system WORL Exiting subroutine D3RORL Output arguments: Orientation unit vectors X axis E -1 N 0 U 0 Y axis E 0 N -1 U 0 Z axis E 0 N 0 U 1 Error code 0 Entering subroutine D3RPRL Input arguments: Coordinate system ZONE Exiting subroutine D3RPRL Output arguments: Position E -314490 N 303145 U 340 Error code 0 Entering subroutine D3RPRL Input arguments: Coordinate system /EQU Exiting subroutine D3RPRL Output arguments: Position E -314490 N 303145 U 100645 Error code 0 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


Version 11.6


XLEN 510.0000 YLEN 1390.000 ZLEN 110.0000 POS 0.0000000E+00 -676.0000 -285.0000 ORI 0.0000000E+00 0.0000000E+00 0.0000000E+00 LEVE 0 10 OBST 2 Exiting D3QBOX Exiting subroutine D3UMON Entering subroutine D3RPAT Input arguments: PPoint number P1 Coordinate system OWNE Exiting subroutine D3RPAT Output arguments: Position E 255 N -676 U -285 Direction unit vector E 1 N 0 U 0 Bore 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 N 303126 U 100360 Direction unit vector E 0 N -1 U 0 Bore 0 Connection type Error code 0 Entering subroutine D3UMON



Input arguments: Monitoring level NONE Entering D3QNOZ Attributes of NOZZ /1501B-SUCT Entering D3QCMA TYPE NOZZ NAME /1501B-SUCT OWNE /1501B LOCK F Exiting D3QCMA TEMP -100000.0 PRES 0.0000000E+00 POS 0.0000000E+00 0.0000000E+00 0.0000000E+00 ORI 0.0000000E+00 0.0000000E+00 180.0000 CREF /100-B-8/1 CATR /NFAAPAMM ANGL 90.00000 HEIG 100.0000 RADI 0.0000000E+00 DUTY Unset ISPE =0/0 Exiting D3QNOZ Success


Version 11.6

Subroutine Specifications

5 Subroutine Specifications

5.1 Introduction

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

'return' arguments. Return arguments are shown underlined. Input arguments are never modified. The programmer can safely

enter constants. Where the routine specification states that input arguments are converted to upper case or subjected to any other modification, this is carried out upon local variables and the modifications are not returned in the arguments.

Some character input arguments can be abbreviated. Minimum abbreviations are indicated by a '/' embedded in each valid entry. For example, MEMB/ER can be abbreviated to MEMB or MEMBE. However, MEMBO would be rejected. Where any option has no '/', the entry cannot be abbreviated. In a similar way, some character input arguments may be abbreviated in accordance with normal PDMS 11 usage, e.g. ELB/OW.



If character arguments are declared too short for the return data, the action of the routine will depend on the use to which the data is likely to be put. For example, a truncated name attribute returned by D3RNAM will result in an error condition (and a blank string will be returned), whereas a truncated error message returned by D3EMSG will not raise an error condition. The action in each case is described fully in the specification.

All return character arguments are blank padded. The programmer can use the data access utility routine D3ULEN to find the significant length.

Where a data access routine returns a error code, the possible values are indicated in the specification for the routine. Positive values denote an error condition; zero denotes no error. If a positive error code is returned, an internal error flag is set to prevent the next data access routine from executing. If the programmer wishes to cancel an intentional error condition, and error handling has not been switched off by D3ECHK, then routine D3ERST must be called to reset the error flag before the next routine is called. The programmer should not call D3ERST without proper cause, otherwise the purpose of the error flag is negated.


Version 11.6


5.2 Subroutine Summaries

5.2.1 Initialisation Routines, D3Ixxx

D3INIT Initialise This routine initialises the system for the PDMS data access routines and sets the monitoring level. It validates the project name and the username and password nominated in that project, all of which may be entered as routine arguments or interactively. It opens the required database files and records the presence of the user in the PDMS system.

5.2.2 Navigation Routines, D3Mxxx

D3MMDB Select an MDB This routine selects an MDB within the requested PDMS project, opens the MDB databases and navigates to the default database world. The user has the option of specifying the default database type or can allow it to default to the type of the first MDB database. D3MCDB Make a Database Current in MDB This routine makes a named database in the current MDB current at the specified position. Other databases are shuffled up or down, as necessary. This is equivalent to the PDMS command CURRENT. D3MEDB Exchange Databases in MDB This routine exchanges a current and a deferred database in the current MDB. One of the named databases must have 'current' status and the other must have 'deferred' status. Their status and list order position will be reversed. is equivalent to the PDMS command EXCHANGE. D3MDDB Defer a Database in MDB This routine defers a named database in the current MDB. This is equivalent to the PDMS command DEFER. D3MQDB Query Database in Current MDB This routine reads the name and status of the database in a defined position in the current MDB. If executed within a loop, this is equivalent to the PDMS command STATUS.



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

5.2.3 Read Routines, D3Rxxx

D3RPRJ Read Project Data Item This routine retrieves project code, name, number, description or message from the System Database. D3RTYP Read the PDMS Type of the Current Element This routine reads the PDMS 'type' attribute of the current element. D3RPRL Read the Position of the Current Element


Version 11.6


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



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 (i.e. P1, P2 etc.) D3RUDA Read Lists of UDA Names, Abbreviations and Types This routine reads, for a specified element type, parallel lists of UDA names, lengths of minimum valid abbreviations and attribute types. D3RUNI Read Unit of Measurement for a Real or Integer UDA This routine returns a text string indicating the UNIT (of measurement) which applies to the specified UDA. Only real or integer attributes may have a UNIT specified. This routine will generally be used in conjunction with the attribute retrieval routines (D3RINT, D3RIA, D3RREA and D3RRA). D3RPTX Read REPORTER Text for a UDA This routine reads the REPORTER text for a given UDA. REPORTER text may be up to 20 characters long and is used in column headers by the PDMS module REPORTER. D3RDAT Read Latest MDB Date-Stamp This routine returns the latest date-stamp for any database in the mdb system.


Version 11.6


D3RBDU Read Bore and Distance Units This routine returns the bore and distance units defined for the current MDB. It returns two character strings containing the linear units. D3RBOX Read Enclosing Box Co-ordinates This routine reads the co-ordinates of the surrounding box for the current element or its leave tube. This is valid for any database element and is equivalent to the CLASHER command 'QUERY BOX'.

5.2.4 Error Handling Routines, D3Exxx

D3ECHK Switch Error Handling ON and OFF This routine enables the user to switch the internal error handling mechanism on and off. The default action at program entry is for error handling to be switched ON. D3EMSG Return Error Message for a given Error Code Most data access routines return an error code to denote an error condition. If the programmer wishes to output the nature of the error, he may call this routine. It returns the error message corresponding to a given error code. The routine will display the error message if requested. D3ERST Reset Internal Error Flag This routine resets the PDMS data access internal error flag. Whenever a positive error code is returned by a PDMS data access routine, an internal error flag is set to prevent the next routine from executing. If the programmer wishes to cancel an intentional error condition and error handling has not been switched off by D3ECHK, then this routine must be called to reset the error flag before the next routine is called.

5.2.5 Utility Routines, D3Uxxx

D3UMON Change Monitor Level



This routine sets or resets the monitoring level. It re-defines the level set in the last call to the routine or set in D3INIT. D3UDEH Dehash a Hashed PDMS Word This routine converts a hashed PDMS word (a PDMS word represented as an integer number) into the PDMS word.1

D3ULDS Test Latest MDB Date-Stamp This routine checks whether any database in the current MDB has been date-stamped later than a specified date/time. It is a utility routine built on routine D3RDAT. D3UINI Query Initialisation This routine returns a true or false flag, depending on whether or not a PDMS project is currently initialised.

5.2.6 Termination Routines, D3Fxxx

D3FIN Finish This is the termination routine for the current PDMS project. It closes all the database files. Access to another PDMS project requires a further call to D3INIT. D3FEND Exit With the withdrawal of D3IBEG at Mk10.2, this routine has become an optional way of stopping a DARs application program. It results in a program exit and is equivalent to a CALL EXIT statement.

5.2.7 General Utility Routines, D3Uxxx

D3UGTU Get File Unit This function allocates an unused FORTRAN file unit for use by the application program. 1 Prior to PDMS 11.1, a PDMS word was represented by a real number.


Version 11.6


D3UCLU Clear File Unit This function cancels an allocated FORTRAN file unit no longer required by the application program. D3ULEN Length of Character String This function returns the significant length of a character string. That is, the length after stripping off all trailing blanks. D3UCTI Character to Integer This function converts the digits in a given string to an integer value. It will also extract the first valid integer from a string containing other characters. D3UCTR Character to Real Number This function converts the digits in a given string to a real number. It will also extract the first valid real number from a string containing other characters. The number may be in decimal or exponential format. D3UDTM Return System Date and Time This routine returns the current system date and time in two formats.

5.3 Detailed Subroutine Specifications

The following pages provide the subroutine specifications for all PDMS and general utility routines in alphabetical order. Each subroutine specification contains the following: 1. The subroutine (or function) statement. 2. The type declaration for each argument as it appears in the routine. 3. A description of the function of the routine. 4. A full definition of each argument. 5. A list of possible returned error codes. 6. Other possible errors and warnings.



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


Version 11.6


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. The routine will display the error message if requested.

Arguments ID3ERR Error code for which the corresponding message is required.

If the value is invalid, the message 'Unknown error' is returned. LD3DIS Display flag.

.TRUE. - display error message to the default device

.FALSE. - display nothing CD3MSG Error message corresponding to error code.

Maximum length of text string is 50 characters. If the supplied character field is shorter than the returned message, the message will be truncated but no error condition will arise. If the field is too long, it will be padded with blanks. The returned (and printed) error message will be as listed in this section of the User Guide and in Appendix C.



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.


Version 11.6


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

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.


Version 11.6


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.

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.


Version 11.6


Arguments CD3PRJ PDMS project name (3 characters), e.g. 'XXX'

Input characters will be converted to upper case. Strings exceeding three characters will be truncated. If the argument is blank (' '), the routine will prompt the user interactively for the project name in the manner of the PDMS entry procedure. The user is allowed three attempts to enter a valid project name. As with PDMS, a valid but non-existent project name will result in an error condition (error 108).

CD3USR PDMS Username (up to 32 characters), e.g. 'SMITH'

Input characters will be converted to upper case. 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.


Version 11.6


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 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. 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


Version 11.6


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.

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.

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


Version 11.6


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. 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.


Version 11.6


Arguments CD3MDB

Default database (up to 9 characters) & MDB Name (up to 32 characters, including the leading '/'), concatenated together.

The default database is interpreted as the text string preceding the first '/' and it will be converted to upper case. If omitted (CD3MDB starts with a '/'), the default database will be the first database in the MDB. The following keywords are valid:

Keyword Default database Other databases open DES/IGN Design (DESI) CATA PROP DICT CAT/ALOGUE Catalogue (CATA) PROP DICT PROP/ERTY Properties (PROP) CATA DICT PAD/DLE PADDLE (PADD) DESI CATA PROP DICT DIC/TIONARY Dictionary (DICT) None Blank or null 1st database All

If a default database is specified, all databases of the types specified in the above table are opened by this routine. The MDB name (the string commencing with the first '/'), e.g. '/MDB1' will NOT be converted to upper case (MDB name is case-sensitive). Names e

Documents

Data Access Routines User Guide