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

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
1.1

Introduction
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
2.1

Programming Techniques
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 INTEGER REAL LOGICAL

CD3xxx ID3xxx RD3xxx 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(*) CD3XYZ

CHARACTER*(*)

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

D3ULEN D3UCTI D3UCTR D3UGTU 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 = 'ABC' CD3XYZ

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 ' ABC'

2:2

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.

Move to first member CALL D3MREL( 'FIRS', 'MEMB', ID3ERR )

20

CONTINUE IF ( ID3ERR .EQ. 0 ) THEN NMEMB = NMEMB + 1

Read type CALL D3RTYP( CD3TEX, ID3ERR ) IF ( ID3ERR .NE. 0 ) GOTO 12345 CD3TYP(NMEMB) = CD3TEX

Read name/reference CALL D3RNAM( 'NAME', CD3TEX, ID3ERR ) IF ( ID3ERR .NE. 0 ) GOTO 12345 CD3NAM(NMEMB) = CD3TEX ELSE

C C

Reset internal error flag if No Members or List Exhausted 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

Check if reached end of User's arrays IF ( NMEMB .EQ. ID3NIN ) GOTO 100

Move to next member of current list CALL D3MREL( 'NEXT', 'ELEM', ID3ERR ) GOTO 20

C 100 . . 12345

End of list CONTINUE

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
3.1

Basic Concepts of PDMS Data Access

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
4.1

Use of Data Access Routines

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 C Application main program Essential type declarations CHARACTER*50 C SPCREF, CATREF

Can declare CD3MSG CHAR*1 if not using it CHARACTER*1 CHARACTER*6 CD3MSG 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 INTRINSIC ID3ERR, ID3NOU, I 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 C Get parameters of component and dehash conn types 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, ' ENDIF 100 C CONTINUE 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 C 12345 C CONTINUE Cancel monitor and output message CALL D3UMON('NONE') CALL D3EMSG( ID3ERR, .TRUE., CD3MSG ) C Exit project CALL D3FIN( ID3ERR ) C Exit DARs CONTINUE ', CD3WOR

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 Username Password Monitoring level Read/Write key Exiting subroutine D3INIT Output arguments: Error code 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:

DAR SYSTEM XXXXXX FULL

108

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 Username Password Monitoring level Read/Write key Exiting subroutine D3INIT Output arguments: Error code 0 DAR SYSTEM XXXXXX FULL

Entering subroutine D3MMDB Input arguments: MDB name Read/Write key DESIGN/PLANT

Opening databases Mode ---Read Read Type ---DESI DESI Name ---STRUC/S

PIPE/MAXDBLENGTH31AFTERTHESLASH Read Read CATA PROP CATAL/C PIPE/PROP

4:5

12.0

Data Access Routines User Guide

Use of Data Access Routines

Read Read

DESI DICT

PIPE/DR PIPE/DR

Default database type: DESI Exiting subroutine D3MMDB Output arguments: Error code Entering subroutine D3MNAM Input arguments: Element name/ref Exiting subroutine D3MNAM Output arguments: Error code Entering subroutine D3MNUM Input arguments: Element type List position Exiting subroutine D3MNUM Output arguments: Error code Entering subroutine D3MREL Input arguments: Relative position Element type Exiting subroutine D3MREL Output arguments: Error code Entering subroutine D3RNAM Input arguments: Attribute required SPRE 0 LAST FLAN 0 BRAN 1 0 /100-B-1 0

4:6

12.0

Data Access Routines User Guide

Use of Data Access Routines

Exiting subroutine D3RNAM Output arguments: Name/Reference Error code Entering subroutine D3MNAM Input arguments: Element name/ref Exiting subroutine D3MNAM Output arguments: Error code Entering subroutine D3RNAM Input arguments: Attribute required Exiting subroutine D3RNAM Output arguments: Name/Reference Error code Entering subroutine D3MNAM Input arguments: Element name/ref Exiting subroutine D3MNAM Output arguments: Error code Entering subroutine D3UMON Input arguments: Monitoring level Getting elements with D3RRA Number of elements found: Element Element 1 2 100.0000 254.0000 NONE 0 /FUAAPAMM /FUAAPAMM 0 CATR 0 /A3B/100F1 /A3B/100F1 0

4:7

12.0

Data Access Routines User Guide

Use of Data Access Routines

Element Element Element Element Element Element

3 4 5 6 7 8

31.80000 54.10000 25.00000 114.3000 BWD FGD

Getting elements with D3RWA Element Element Success 7 8 BWD FGD

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 EXTERNAL IFINDM 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

Exit

12345 CONTINUE CALL D3FIN( IFINDM ) CALL D3FEND END

C-----------------------------LOGICAL FUNCTION PROJIN() C-----------------------------CHARACTER*1 C TEXT

Optional declarations INTEGER EXTERNAL IERR 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 EXTERNAL IERR 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---------------------CHARACTER*50 CHARACTER*6 LOGICAL LOGICAL CHARACTER*50 CHARACTER*50 CHARACTER*50 CHARACTER*120 INTEGER INTEGER INTEGER REAL REAL C TEXT, NAMES(100) TYPES(100), LNTP TYPE, HCON, TCON, FLOW,

LOCK, BUIL, LHEA, LTAI, DETA, SHOP, LSTR ORIL, POSI, LOFF NAME, OWNE, MATR FLUR, CASR, PSPE, ISPE, TSPE HSTU, HREF, TREF, SPRE, CATR, LSTU, CREF DUTY, DSCO, PTSP, INSC, FUNC REV , EREC, CCEN, CCLA, SAFC LEVE(2), OBST, ARRI D3XLEN HPOS(3), POS(9) HDIR(3), TPOS(3), TDIR(3),

ORI(3), ANGL

Optional declarations INTEGER REAL REAL EXTERNAL ISIZ, IERR, LEAV, IDISP XLEN, YLEN, ZLEN, HEIG, RADI BORE, HBOR, TBOR, TEMP, PRES D3MNAM, D3MNUM, D3MREL, D3RORL D3UMON, D3RPAT,

4:10

12.0

Data Access Routines User Guide

Use of Data Access Routines

EXTERNAL EXTERNAL EXTERNAL

D3RPRL, D3EMSG D3QMEM, D3QSIT, D3QPIP, D3QBRA D3QTEE, D3QELB, D3QNOZ, D3MMDB D3XLEN, D3QEQU, D3QZON, 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*, ' '

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)) 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, name /EQU got ',

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)) 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 ) /250-B-5 got ',

IF ( IERR .NE. 0 ) GOTO 12345 IF ( NAME .NE. '/250-B-5/1' ) THEN PRINT*,'Expecting name ',NAME(:D3XLEN(NAME)) GOTO 12345 ENDIF C Branch PPoints with Monitoring CALL D3UMON( 'FULL' ) CALL D3RPAT( 'PH', '/EQ3', POS(1), POS(4), BORE, HCON, IERR ) /250-B-5/1 got

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)) 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 name /1501B got ',

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, CATR, ANGL, HEIG, RADI,

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

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 2 3 4 5 6 7 8 9 10 SITE SITE SITE SITE SITE SITE SITE SITE SITE GPWL /* /NEGATIVE-SITE /DIMENSION-SITE /VOLCAL.SITE /EX1-SITE /HANG-SITE /CIVIL /INTEST-SITE /EQU /OBSTR /GW1

Exiting D3QMEM

Entering D3QMEM

4:17

12.0

Data Access Routines User Guide

Use of Data Access Routines

Members of SITE 1 2 3 ZONE ZONE ZONE

/EQU /EQ1 /EQ2 /EQ3

Exiting D3QMEM

Entering D3QSIT Attributes of SITE Entering D3QCMA TYPE NAME OWNE LOCK SITE /EQU /* F /EQU

Exiting D3QCMA POS ORI 0.0000000E+0 0 0.0000000E+0 0 0.0000000E+00 0.0000000E+00 0.0000000E+ 00 0.0000000E+ 00

Exiting D3QSIT

Entering D3QMEM Members of ZONE 1 2

3 4 5 6 7 8 9

/EQ3 /EQUIP-FALL /FALL /100-B-2 /50-W-3000 /50-WD-2400 /50-W1-3400 /80-S12-1400 /200-N12-1000 /50-N12-1800

EQUI PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE

4:18

12.0

Data Access Routines User Guide

Use of Data Access Routines

10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE PIPE

/150-W12-2000 /150-W12-2200 /100-C-12 /100-C-13 /150-A-57 /150-A-3 /40-B-10 /80-A-11 /80-B-14 /100-B-1 /80-B-7 /150-B-6 /100-B-8 /50-B-9 /200-B-4 /250-B-5

Exiting D3QMEM

Entering D3QZON Attributes of ZONE /EQ3 Entering D3QCMA TYPE NAME OWNE LOCK ZONE /EQ3 /EQU F

Exiting D3QCMA POS ORI PSPE 0.0000000E+0 0 0.0000000E+0 0 =0/0 0.0000000E+00 0.0000000E+00 100000.0 0.0000000E+ 00

4:19

12.0

Data Access Routines User Guide

Use of Data Access Routines

ISPE TSPE

=0/0 =0/0

Exiting D3QZON

Entering D3QMEM Members of PIPE

1 2

/250-B-5 /250-B-5/1 /250-B-5/2

BRAN BRAN

Exiting D3QMEM

Entering D3QPIP Attributes of PIPE Entering D3QBPA Entering D3QCMA TYPE NAME OWNE LOCK PIPE /250-B-5 /EQ3 F /250-B-5

Exiting D3QCMA BUIL SHOP TEMP PRES PSPE ISPE TSPE MATR FLUR CASR CCEN F F -100000.0 0.0000000E+00 /A3B =0/0 =0/0 =0/0 =0/0 =0/0 0

4:20

12.0

Data Access Routines User Guide

Use of Data Access Routines

CCLA DUTY LNTP EREC DSCO PTSP INSC SAFC Exiting D3QBPA BORE REV Exiting D3QPIP 0.0000000E+00 Unset Unset Unset Unset Unset

-1

Entering D3QMEM Members of BRAN

1 2 3 4 5 6 7 8 9

/250-B-5/1 =8196/556 =8196/557 =8196/558 =8196/559 =8196/560 /250-B-5/1-T1 =8196/562 =8196/563 =8196/564 =8196/565 =8196/566

GASK FLAN ELBO ELBO REDU TEE REDU ELBO ELBO FLAN GASK

10 11

Exiting D3QMEM

Entering D3QBRA Attributes of BRAN /250-B-5/1

4:21

12.0

Data Access Routines User Guide

Use of Data Access Routines

Entering D3QBPA Entering D3QCMA TYPE NAME OWNE LOCK BRAN /250-B-5/1 /250-B-5 F

Exiting D3QCMA BUIL SHOP TEMP PRES PSPE ISPE TSPE MATR FLUR CASR CCEN CCLA DUTY LNTP EREC DSCO PTSP INSC SAFC Exiting D3QBPA LHEA LTAI DETA T T F Unset Unset Unset 0 Unset Unset 0 T T 466.0000 340.0000 /A3B =0/0 =0/0 =0/0 =0/0 =0/0 0 0

4:22

12.0

Data Access Routines User Guide

Use of Data Access Routines

LSTR HBOR TBOR HCON TCON FLOW HSTU HREF TREF HPOS HDIR TPOS TDIR

F 200.0000 200.0000 FGD FGD Unset /A3B/200P /1301-S2 /1301-S3 -319150.0 0.0000000E+0 0 -319150.0 0.0000000E+0 0 297760.0 0.0000000E+00 302640.0 0.0000000E+00 2105.000 1.000000 2105.000 1.000000

Exiting D3QBRA

Exiting subroutine D3UMON Entering subroutine D3RPAT Input arguments: PPoint number Coordinate system Exiting subroutine D3RPAT Output arguments: Position E -319150 N 297760 N 0 U 1 U 2105 PH /EQ3

Direction unit vector E 0 Bore Connection type Error code Entering subroutine D3RPAT Input arguments: 200 FGD 0

4:23

12.0

Data Access Routines User Guide

Use of Data Access Routines

PPoint number Coordinate system Exiting subroutine D3RPAT Output arguments: Position E -319150 Direction unit vector Bore Connection type Error code Entering subroutine D3UMON Input arguments: Monitoring level Entering D3QTEE Attributes of TEE Entering D3QCPA Entering D3QCMA TYPE NAME OWNE LOCK TEE /250-B-5/1-T1 /250-B-5/1 F

ptail worl

N 302640 E 0 200 FGD 0 N 0

U 102105 U 1

NONE

/250-B-5/1-T1

Exiting D3QCMA POS ORI SPRE LSTU BUIL SHOP ORIFL POSFL ISPE -318315.3 0.0000000E+0 0 /A3B/250T =0/0 F F T T =0/0 300229.6 0.0000000E+00 3886.000 0.0000000E+ 00

4:24

12.0

Data Access Routines User Guide

Use of Data Access Routines

TSPE

=0/0

Exiting D3QCPA CREF ANGL HEIG RADI LOFF /250-B-5/2 90.00000 0.0000000E+00 0.0000000E+00 F

Exiting D3QTEE

Entering D3QELB Attributes of ELBO =8196/559 Entering D3QCPA Entering D3QCMA TYPE NAME OWNE LOCK ELBO =8196/559 /250-B-5/1 F

Exiting D3QCMA POS ORI SPRE LSTU BUIL SHOP ORIFL POSFL ISPE TSPE -318315.3 180.0000 /A3B/200EL /A3B/200P F F T T =0/0 =0/0 297759.1 0.0000000E+00 3885.950 90.00000

Exiting D3QCPA CREF =0/0

4:25

12.0

Data Access Routines User Guide

Use of Data Access Routines

ANGL RADI

90.00000 0.0000000E+00

Exiting D3QELB

Exiting subroutine D3UMON Entering subroutine D3RPAT Input arguments: PPoint number Coordinate system Exiting subroutine D3RPAT Output arguments: Position E -318620 Direction vector Bore Connection type Error code Entering subroutine D3RPAT Input arguments: PPoint number Coordinate system Exiting subroutine D3RPAT Output arguments: Position E -318315 Direction vector Bore Connection type Error code Entering subroutine D3UMON Input arguments: unit N 298064 E 0 200 BWD 0 N 1 U 0 U 103886 P2 WORL unit N 297759 E -1 200 BWD 0 N 0 U 0 U 103886 P1 WORL

4:26

12.0

Data Access Routines User Guide

Use of Data Access Routines

Monitoring level

NONE

Entering D3QMEM Members of EQUI 1

2 3 4 5 6 7

/1501B =8196/151 =8196/152 =8196/153 =8196/154 =8196/155 /1501B-SUCT /1501B-DISC

BOX PYRA CYLI CYLI RTOR NOZZ NOZZ

Exiting D3QMEM

Entering D3QEQU Attributes of EQUI Entering D3QCMA TYPE NAME OWNE LOCK EQUI /1501B /EQ2 F /1501B

Exiting D3QCMA FUNC DSCO PTSP INSC POS ORI ISPE Unset Unset Unset Unset -314490.0 0.0000000E+0 0 =0/0 303145.0 0.0000000E+00 340.0000 180.0000

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

4:28

12.0

Data Access Routines User Guide

Use of Data Access Routines

Coordinate system Exiting subroutine D3RPRL Output arguments: Position E -314490 Error code Entering subroutine D3UMON Input arguments: Monitoring level

/EQU

N 303145 0

U 100645

NONE

Entering D3QBOX Attributes of BOX Entering D3QCMA TYPE NAME OWNE LOCK BOX =8196/151 /1501B F =8196/151

Exiting D3QCMA XLEN YLEN ZLEN POS ORI LEVE OBST 510.0000 1390.000 110.0000 0.0000000E+0 0 0.0000000E+0 0 0 2 -676.0000 0.0000000E+00 10 -285.0000 0.0000000E+ 00

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 Coordinate system Exiting subroutine D3RPAT Output arguments: Position

P1 OWNE

E 255

N -676 N 0 U 0

U -285

Direction unit vector E 1 Bore Connection type Error code Entering subroutine D3RPAT Input arguments: PPoint number Coordinate system Exiting subroutine D3RPAT Output arguments: Position Direction unit vector Bore Connection type Error code Entering subroutine D3UMON Input arguments: Monitoring level NONE
0

P2 WORL

E -314490 100360 E 0 0 N -1

303126 U 0

Entering D3QNOZ Attributes of NOZZ Entering D3QCMA TYPE NAME OWNE NOZZ /1501B-SUCT /1501B /1501B-SUCT

4:30

12.0

Data Access Routines User Guide

Use of Data Access Routines

LOCK

Exiting D3QCMA TEMP PRES POS ORI CREF CATR ANGL HEIG RADI DUTY ISPE -100000.0 0.0000000E+0 0 0.0000000E+0 0 0.0000000E+0 0 /100-B-8/1 /NFAAPAMM 90.00000 100.0000 0.0000000E+0 0 Unset =0/0 0.0000000E+00 0.0000000E+00 0.0000000E+ 00 180.0000

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
5.1
5.1.1

Subroutine Specifications
Subroutine Summaries
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*(*)

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

CD3ERR

D3EMSG - Return Error Message

Specification

SUBROUTINE D3EMSG( ID3ERR, LD3DIS, CD3MSG ) CHARACTER*(*) LOGICAL INTEGER

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.

CD3MSG LD3DIS ID3ERR

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

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.

ID3ERR

5:8

12.0

Data Access Routines User Guide

Subroutine Specifications

Arguments ID3ERR Possible values are: Error code (not used; for possible future use) Any error code set prior to this routine is preserved and returned.

D3INIT - Initialise
Specification

SUBROUTINE D3INIT( CD3PRJ, CD3USR, CD3PAS, CD3MON, CD3RWK, ID3ERR ) CHARACTER*(*) INTEGER
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.

CD3PRJ, CD3USR, CD3PAS, CD3MON, CD3RWK ID3ERR

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 Possible values are: 0 2 101 102 103 Success Internal error code set on entry Error opening Dabacon workfile Bad password Unknown username Error code.

5:10

12.0

Data Access Routines User Guide

Subroutine Specifications

104 105 106 107 108 109 115 116 119

Too many users in project Project currently locked Project is incompatible version Too many failed initialisations Project not found Error opening runfile data file Sitefile/Security error Invalid project name 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*(*) INTEGER

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 ID3POS The name of the database. 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.

CD3NAM ID3POS, ID3ERR

5:11

12.0

Data Access Routines User Guide

Subroutine Specifications

Possible values are: 0 2 3 4 120 121 122 124 125 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Database not found Database not in current MDB Database already current Too many current databases Invalid database position

D3MDDB - Defer a Database in MDB

Specification

SUBROUTINE D3MDDB( CD3NAM, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3NAM ID3ERR

5:12

12.0

Data Access Routines User Guide

Subroutine Specifications

Arguments CD3NAM ID3ERR Possible values are: 0 2 3 4 120 121 123 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Database not found Database not in current MDB Database not current The name of the database. Error code.

D3MEDB - Exchange Databases in MDB

Specification

SUBROUTINE D3MEDB( CD3NM1, CD3NM2, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3NM1, CD3NM2 ID3ERR

5:13

12.0

Data Access Routines User Guide

Subroutine Specifications

Arguments CD3NM1 CD3NM2 The name of the first database. The name of the second database. The order of the two databases is not important. ID3ERR Possible values are: 0 2 3 4 120 121 122 123 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Database not found Database not in current MDB Database already current (i.e. both are current) Database not current (i.e. both are deferred) Error code.

D3MMDB - Select MDB

Specification

SUBROUTINE D3MMDB( CD3MDB, CD3RWK, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3MDB, CD3RWK ID3ERR

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 DES/IGN CAT/ALOGUE PROP/ERTY PAD/DLE DIC/TIONARY Blank or null Default database Design (DESI) Catalogue (CATA) Properties (PROP) PADDLE (PADD) Dictionary (DICT) 1st database Other databases open CATA PROP DICT PROP DICT CATA DICT DESI CATA PROP DICT None 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 CAT/TEST /PLANT CD3RWK : Default database DESI, MDB /PLANT : Default database CATA, MDB /TEST : No default database (defaults to first), MDB /PLANT Read/write key (for future use) Enter as ' ' in this release. The argument will be ignored. ID3ERR Possible values are: 0 2 Success Internal error code set on entry Error code.

5:15

12.0

Data Access Routines User Guide

Subroutine Specifications

3 110 111 112 113 114 117 118

Routine D3INIT has not been called MDB not found No databases to open Corrupt databases Databases in use Error opening database file Invalid default database type No databases of default type in MDB

D3MNAM - Move to an Element by Name

Specification

SUBROUTINE D3MNAM( CD3NAM, ID3ERR ) CHARACTER*(*) INTEGER

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 Possible values are: 0 2 3 4 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Error code.

CD3NAM ID3ERR

5:16

12.0

Data Access Routines User Guide

Subroutine Specifications

9 402

Bad name/reference argument Undefined name/reference

D3MNUM - Move to Element by Order Position

Specification

SUBROUTINE D3MNUM( CD3TYP, ID3LIS, ID3ERR ) CHARACTER*(*) INTEGER

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:

CD3TYP ID3LIS, ID3ERR

ELEM/ENT MEMB/ER
ID3LIS

Move in the current list Move to a member owned by the current element 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 Possible values are: 0 2 3 4

Error code.

Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called

5:17

12.0

Data Access Routines User Guide

Subroutine Specifications

10 201 202 203 205

Argument has illegal value Element has no list part No members List exhausted Cannot access this type of element

D3MOWN - Move to Owner of Current Element

Specification

SUBROUTINE D3MOWN( ID3ERR ) INTEGER

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 Possible values are: 0 2 3 4 204 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Current element has no owner Error code.

ID3ERR

D3MQDB - Query database in Current MDB

Specification

SUBROUTINE D3MQDB( ID3POS, CD3NAM, CD3TYP, ID3STA, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3NAM, CD3TYP ID3POS, ID3STA, ID3ERR

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 CD3NAM The list order position of the database. 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: 2: 3: Current, Read Current, Closed Deferred

ID3STA will be returned as zero if the routine fails. ID3ERR Possible values are: 0 2 3 4 125 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Invalid database position Error code

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*(*) INTEGER

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:

CD3POS, CD3TYP ID3ERR

FIRS/T LAST NEXT PREV/IOUS

CD3TYP

first element last element next element previous element 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 MEMB/ER
TID3ERR Possible values are: 0 2

Move in the current list Move to a member owned by the current element Error code

Success Internal error code set on entry

5:20

12.0

Data Access Routines User Guide

Subroutine Specifications

3 4 6 201 202 203 205

Routine D3INIT has not been called Routine D3MMDB has not been called Invalid position keyword Element has no list part No members List exhausted Cannot access this type of element

D3MRST - Restore Last Saved Database Position

Specification

SUBROUTINE D3MRST( ID3ERR ) INTEGER

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 Possible values are: 0 2 3 4 127 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called No saved database position Error code.

ID3ERR

5:21

12.0

Data Access Routines User Guide

Subroutine Specifications

D3MSAV - Save Current Database Position

Specification

SUBROUTINE D3MSAV( ID3ERR ) INTEGER

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 Possible values are: 0 2 3 4 126 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Too many saved database levels Error code.

ID3ERR

D3RBDU - Read Bore and Distance Units

Specification

SUBROUTINE D3RBDU( CD3BUN, CD3DUN, ID3ERR ) CHARACTER*(*)

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.

CD3BUN, CD3DUN

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 Possible values are: 0 2 3 4

Error code.

Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called

D3RBOX - Read Enclosing Box Co-ordinates

Specification

SUBROUTINE D3RBOX LOGICAL INTEGER REAL

Description

( LD3TUB, RD3BOX, ID3ERR ) LD3TUB ID3ERR RD3BOX(6)

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. Return box for leave tube (or branch head tube for branch) Return box for current element 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 Possible values are: 0 2 3 4 309 310 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Element not on spatial map Leave or head tube does not exist Error code.

.TRUE. .FALSE.
RD3BOX

D3RDAT - Read Latest MDB Date-Stamp

Specification

SUBROUTINE D3RDAT( ID3DAT, CD3DAT, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3DAT ID3DAT(6), ID3ERR

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) ID3DAT(2) ID3DAT(3) ID3DAT(4) ID3DAT(5) ID3DAT(6)

Year (As a 4-digit number) Month (1 = January, 12 = December) Day (1 to 31) Hour (0 to 23) Minute (0 to 59) 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: 11-16: 17-19: returns blank string returns dd Mon yy 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 Possible values are: 0 2 3 Success Internal error code set on entry Routine D3INIT has not been called Error code.

5:25

12.0

Data Access Routines User Guide

Subroutine Specifications

4 306

Routine D3MMDB has not been called No date-stamp found

D3RIA - Read an Integer Array Attribute

Specification

SUBROUTINE D3RIA( CD3ATT, ID3NIN, ID3IA, ID3NOU, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3ATT ID3NIN, ID3IA(ID3NIN), ID3NOU, ID3ERR

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 Possible values are: 0 2 3 4 301 302 308 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Attribute not found Attribute of wrong type Attribute unset Error code.

5:27

12.0

Data Access Routines User Guide

Subroutine Specifications

D3RINT - Read an Integer Attribute

Specification

SUBROUTINE D3RINT( CD3ATT, ID3INT, ID3ERR ) CHARACTER*(*) INTEGER

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 Possible values are: 0 2 3 4 301 302 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Attribute not found Attribute of wrong type Error code.

CD3ATT ID3INT, ID3ERR

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*(*) INTEGER LOGICAL
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 ID3NOU The array of logical values. 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.

CD3ATT ID3NIN, ID3NOU, ID3ERR LD3LA(ID3NIN)

5:29

12.0

Data Access Routines User Guide

Subroutine Specifications

ID3ERR Possible values are: 0 2 3 4 301 302 308

Error code.

Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Attribute not found Attribute of wrong type Attribute unset

D3RLOG - Read a Logical Attribute

Specification

SUBROUTINE D3RLOG( CD3ATT, LD3LOG, ID3ERR ) CHARACTER*(*) INTEGER LOGICAL

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 ID3ERR Possible values are: The value of the logical attribute. Error code.

CD3ATT ID3ERR LD3LOG

5:30

12.0

Data Access Routines User Guide

Subroutine Specifications

0 2 3 4 301 302

Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Attribute not found Attribute of wrong type

D3RNAM - Read Element Name or a Name Attribute

Specification

SUBROUTINE D3RNAM( CD3ATT, CD3NAM, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3ATT, CD3NAM ID3ERR

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 Possible values are: 0 2 3 4 5 301 302 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Attribute not found Attribute of wrong type Error code.

D3RORL - Read Orientation of the Current Element

Specification

SUBROUTINE D3RORL( CD3CRD, RD3ORI, ID3ERR ) CHARACTER*(*) INTEGER REAL

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.

CD3CRD ID3ERR RD3ORI(9)

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 Possible values are: 0 2 3 4 7 9 205 402 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Invalid co-ordinate system keyword Bad name/reference argument Cannot access this type of element Undefined name/reference Error code.

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*(*) INTEGER REAL
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).

CD3POI, CD3CRD, CD3CON ID3ERR RD3POS(3), RD3DIR(3), RD3BOR

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 CD3CON The PPoint bore. 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 2 3 4 5 7 8 9 205 303 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Invalid co-ordinate system keyword Invalid PPoint keyword Bad name/reference argument Cannot access this type of element Element does not have PPoints

5:35

12.0

Data Access Routines User Guide

Subroutine Specifications

304 402

Illegal PPoint number Undefined name/reference

D3RPRJ - Read a Project Data Item

Specification

SUBROUTINE D3RPRJ( CD3NAM, CD3TEX, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3NAM, CD3TEX ID3ERR

The following keywords are valid:

COD/E NUM/BER NAM/E DES/CRIPTION MES/SAGE

project code project number project name project description 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 Possible values are: 0 2 3 5 11 Success Internal error code set on entry Routine D3INIT has not been called Character output string parameter too short Invalid project data keyword Error code.

D3RPRL - Read Position of the Current Element

Specification

SUBROUTINE D3RPRL( CD3CRD, RD3POS, ID3ERR ) CHARACTER*(*) INTEGER REAL

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.

CD3CRD ID3ERR RD3POS(3)

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 Possible values are: 0 2 3 4 7 9 205 402 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Invalid co-ordinate system keyword Bad name/reference argument Cannot access this type of element Undefined name/reference Error code.

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*(*) INTEGER

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:

CD3ATT, CD3RPT ID3ERR

: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 Possible values are: 0 2 3 4 307 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called UDA not found Error code.

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*(*) INTEGER REAL
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.

CD3ATT ID3NIN, ID3NOU, ID3ERR RD3RA(ID3NIN)

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 Possible values are: 0 2 3 4 301 302 308

Error code.

Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Attribute not found Attribute of wrong type Attribute unset

D3RREA - Read a Real Attribute

Specification

SUBROUTINE D3RREA( CD3ATT, RD3REA, ID3ERR ) CHARACTER*(*) INTEGER REAL

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.

CD3ATT ID3ERR RD3REA

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 Possible values are: 0 2 3 4 301 302 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Attribute not found Attribute of wrong type Error code.

D3RREF - Read Element RefNo or a Reference Attribute

Specification

SUBROUTINE D3RREF( CD3ATT, CD3REF, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3ATT, CD3REF ID3ERR

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 Possible values are: 0 2 3 4 5 301 302 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Attribute not found Attribute of wrong type Error code.

D3RRFA - Read a Reference Number Array Attribute

Specification

SUBROUTINE D3RRFA( CD3ATT, ID3NIN, CD3RFA, ID3NOU, ID3ERR ) CHARACTER*(*) INTEGER

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

ID3NIN, ID3NOU, ID3ERR CD3ATT, CD3RFA(ID3NIN)

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 Possible values are: 0 2 3 4 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Error code.

5:44

12.0

Data Access Routines User Guide

Subroutine Specifications

5 301 302 308

Character output string parameter too short Attribute not found Attribute of wrong type Attribute unset

D3RTEX - Read a Text Attribute

Specification

SUBROUTINE D3RTEX( CD3ATT, CD3TEX, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3ATT, CD3TEX ID3ERR

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 Possible values are: 0 2 3 4 5 301 302 308 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Attribute not found Attribute of wrong type Attribute unset Error code.

5:46

12.0

Data Access Routines User Guide

Subroutine Specifications

D3RTYP - Read a Type Attribute

Specification

SUBROUTINE D3RTYP( CD3TYP, ID3ERR ) CHARACTER*(*) INTEGER

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 Possible values are: 0 2 3 4 5 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Error code.

CD3TYP ID3ERR

D3RUDA - Read Lists of UDA Names, Abbreviations and Types

Specification

SUBROUTINE D3RUDA( CD3TYP, ID3MAX, CD3NMS, ID3ABV, CD3ATP, ID3NUM, ID3ERR ) CHARACTER*(*) INTEGER
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

ID3MAX, ID3ABV(ID3MAX), ID3NUM, ID3ERR CD3TYP, CD3NMS(ID3MAX), CD3ATP(ID3MAX)

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 : Integer : Reference : Text : Word : Logical

REAL INT REF TEXT WORD LOG

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 Possible values are: 0 2 3 4

Error code.

Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called

D3RUNI - Read Unit of Measurement for a Real or Integer UDA

Specification

SUBROUTINE D3RUNI( CD3ATT, CD3UNT, ID3ERR ) CHARACTER*(*) INTEGER

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.

CD3ATT, CD3UNT ID3ERR

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 Possible values are: 0 2 3 4 5 307 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short UDA not found Error code.

D3RWA - Read a Word Array Attribute

Specification

SUBROUTINE D3RWA( CD3ATT, ID3NIN, CD3WA, ID3NOU, ID3ERR ) CHARACTER*(*) INTEGER

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.

ID3NIN, ID3NOU, ID3ERR CD3ATT, CD3WA(ID3NIN)

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 REAL CHARACTER*6 INTRINSIC

ID3NOU, ID3ERR, I PARA( 100 PARWOR( 100 ) 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 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.

CONTINUE

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 2 3 4 5 301 302 308 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Attribute not found Attribute of wrong type Attribute unset

D3RWOR - Read a Word Attribute

Specification

SUBROUTINE D3RWOR( CD3ATT, CD3WOR, ID3ERR) CHARACTER*(*) INTEGER

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.

CD3ATT, CD3WOR ID3ERR

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 Possible values are: 0 2 3 4 5 301 302 Success Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Character output string parameter too short Attribute not found Attribute of wrong type Error code.

D3UCLU - Clear File Unit

Specification

LOGICAL FUNCTION D3UCLU( ID3UNI ) INTEGER

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.

ID3UNI

5:53

12.0

Data Access Routines User Guide

Subroutine Specifications

Arguments ID3UNI Function Value D3UCLU .TRUE. if file unit number accepted. .FALSE. if unit invalid. FORTRAN file unit number.

D3UCTI - Character to Integer

Specification

LOGICAL FUNCTION D3UCTI( CD3STR, ID3INT, CD3BEF, CD3AFT, CD3ERR ) CHARACTER*(*) INTEGER
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.

CD3STR, CD3BEF, CD3AFT, CD3ERR ID3INT

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 CD3BEF Extracted integer, if found. 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 OOR BLA ADD

Not a number Out of range Blank string 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. .FALSE.

if no integer. if integer found with additional data.

D3UCTR - Character to Real Number

Specification

LOGICAL FUNCTION D3UCTR( CD3STR, RD3VAL, CD3BEF, CD3AFT, CD3ERR ) CHARACTER*(*) REAL
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.

CD3STR, CD3BEF, CD3AFT, CD3ERR RD3VAL

'

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 CD3BEF Extracted value, if found. 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 OOR BLA ADD

Not a number Out of range Blank string 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. .FALSE. .FALSE.

if real number found without additional data. if no real number. if real number found with additional data.

D3UDEH - Dehash a Hashed PDMS Word

Specification

SUBROUTINE D3UDEH( ID3INT, CD3WOR ) CHARACTER*(*) INTEGER CD3WOR 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*(*) INTEGER

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.

CD3DAT ID3DAT(6)

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): ID3DAT(2): ID3DAT(3): ID3DAT(4): ID3DAT(5): ID3DAT(6): Year (As a 4-digit number) Month (1 = January, 12 = December) Day (1 to 31) Hour (0 to 23) Minute (0 to 59) 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: 11-16: 17-19: 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. returns blank string returns dd Mon yy returns dd Mon yy hh:mm

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 Function Value D3UGTU FORTRAN file unit number.

.TRUE. .FALSE.

if file unit number returned. 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. .FALSE.

if a project is not currently initialised if no unit available.

D3ULDS - Test Latest MDB Date-Stamp

Specification

LOGICAL FUNCTION D3ULDS( CD3DAT, ID3ERR ) CHARACTER*(*) INTEGER

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' is '13 Sep 1997 12:15:00'

CD3DAT ID3ERR

'13sept1997 12:15' '13sept1997' ID3ERR Error code.

is '13 Sep 1997 23:59:59'

Possible values are: 0 Success

5:61

12.0

Data Access Routines User Guide

Subroutine Specifications

2 3 4 12 13 Function Value D3ULDS

Internal error code set on entry Routine D3INIT has not been called Routine D3MMDB has not been called Invalid date/time Entered date/time later than current

.TRUE. .FALSE.

if any db date-stamp later than CD3DAT 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*(*)

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.

CD3STR

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*(*)

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

CD3MON

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 SOME FULL no monitoring. If required, D3EMSG can be called selectively to output messages. display names and types of databases opened by D3MMDB. 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
6.1

Version Control
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

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 dar100 d3test.f d3extras.f d3lib.dll d3lib.lib d3test d3test.log.base f77_example1.f f77_example2.f f77_example3.f compload.bat c_example.c cxx_example.cxx ccompload.bat cxxcompload.bat a test project directory for acceptance test a test project directory for acceptance test FORTRAN source file FORTRAN source file DARs Fortran/C/C++ runtime library DARs Fortran/C/C++ link library executable file log file of acceptance test run FORTRAN source for Example 1, see Section 4.2 FORTRAN source for Example 2, see Section 4.3 FORTRAN source for Example 3 dos script to compile and link any source program C source for example program (see C/C++ Library) C++ source for example program DOS script to compile and link any C source program DOS script to compile and link and C++ source program

A:1

12.0

Data Access Routines User Guide

DARs Library Details

d3libc.h pdms.h

C header file to include in any C/C++ source program 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

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

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: 101 - 199: 201 - 299: 301 - 399: 401 - 499:

General Initialisation Navigation Retrieval 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

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.

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.

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

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

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.

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

123

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

124

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

Auxiliary Subroutine Library

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: 1: 2: Display no return arguments Display return arguments (except ID3ERR) 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 D3QCMA D3QUDV Design Database: D3QSIT D3QZON D3QPIP D3QBRA D3QBPA D3QTEE D3QELB D3QCPA D3QEQU D3QNOZ D3QBOX Catalog Database D3QCAT D3QSEC D3QCOM D3QUNI D3QUSE D3QUDE D3QMSE D3QMTY D3QATL D3QSPW Query Attributes for a CATALOG Query Attributes for a SECTION Query Attributes for a SCOMP Query Attributes for a UNIT Query Attributes for a USEC Query Attributes for a UDEF Query Attributes for a MSET Query Attributes for a MTYP Query Attributes for a ATLI Query Attributes for a SPWL Query Attributes for a SITE Query Attributes for a ZONE Query Attributes for a PIPE Query Attributes for a BRANCH Query Attributes Common to PIPE/BRANCH (called by D3QPIP and D3QBRA) Query Attributes for a TEE Query Attributes for an ELBOW Query Attributes Common to Piping Components (called by D3QTEE and D3QELB) Query Attributes for an EQUIPMENT Query Attributes for a NOZZLE Query Attributes for a BOX Query Members for Current Element Query Attributes Common to all Element Types (TYPE, NAME, OWNEr, LOCK) Query UDAs and UDA Values for Current Element

D:2

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

D3QSPE D3QSEL D3QSPC D3QCCT D3QCOC D3QTUB D3QCMP D3QCDA D3QCON

Query Attributes for a SPEC Query Attributes for a SELE Query Attributes for a SPCO Query Attributes for a CCTA Query Attributes for a COCO Properties Database Query Attributes for a TUBD Query Attributes for a CMPD Query Attributes Common to TUBD and CMPD (called by D3QTUB and D3QCMP) Query Attributes for a CONS

Dictionary Database D3QUDA Query Attributes for a UDA

Additional Routine D3XLEN Integer Function returning Significant Length of a String or 1 for a Blank String (variant of D3ULEN)

D.3

Subroutine Outline Specifications

Outline specifications are presented for the auxiliary routines in the order listed above. SUBROUTINE D3QMEM ( ID3DIS, ID3NIN, CD3TYP, CD3NAM, ID3NOU, ID3ERR )

INTEGER CHARACTER*(*)

ID3DIS, ID3NIN, ID3NOU, ID3ERR 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 ID3NIN CD3TYP CD3NAM ID3NOU ID3ERR Display flag Max number of array elements required Array of element types (allow four characters per element) Array of element names (allow 50 characters per element) Number of elements returned for each of above two arrays Error code

D:3

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

SUBROUTINE D3QCMA ( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK 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 TYPE OWNE ID3ERR Display flag Type NAMEName Owner name/ref LOCKLock flag 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 ID3ERR Display flag 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 LOGICAL CHARACTER*(*) REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE POS(3), ORI(3)

Performs the equivalent of a Q ATT for a SITE. Calls D3RNAM, D3XLEN, D3QCMA, D3RRA, D3EMSG ID3DIS TYPE OWNE POS ID3ERR Display flag Type Owner name/ref Position Error code NAME LOCK ORI Name Lock flag Orientation

SUBROUTINE D3QZON( ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI, PSPE,ISPE, TSPE, ID3ERR )

INTEGER LOGICAL CHARACTER*(*) REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, PSPE, ISPE, TSPE POS(3), ORI(3)

Performs the equivalent of a Q ATT for a ZONE. Calls D3RNAM, D3XLEN, D3QCMA, D3RRA, D3EMSG, D3ERST ID3DIS TYPE OWNE POS PSPE TSPE Display flag Type Owner name/ref Position Pipe spec Tracing spec NAME LOCK ORI ISPE ID3ERR Name Lock flag Orientation Insulation spec 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 LOGICAL CHARACTER*(*) CHARACTER*(*) REAL

ID3DIS, CCEN, CCLA, EREC, REV, SAFC, ID3ERR LOCK, BUIL, SHOP TYPE, NAME, OWNE, PSPE, ISPE, TSPE, MATR FLUR, CASR, DUTY, LNTP, DSCO, PTSP, INSC BORE, TEMP, PRES

Performs the equivalent of a Q ATT for a pipe. Calls D3RNAM, D3XLEN, D3QBPA, D3RREA, D3RINT, D3EMSG ID3DIS TYPE OWNE BUIL BORE PRES ISPE MATR CASR CCLA LNTP REV PTSP SAFC Display flag Type Owner name/ref Built flag Pipe bore Pressure Insulation spec Material ref List of cases ref Cost class Line type identifier Revision Paint spec Safety class NAME LOCK SHOP TEMP PSPE TSPE FLUR CCEN DUTY EREC DSCO INSC ID3ERR Name Lock flag Shop flag Temperature Pipe spec Tracing spec Fluid ref Cost centre Duty Erection Design code Inspection schedule Error code LHEA, TEMP, DUTY, TPOS,

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 )

INTEGER LOGICAL

ID3DIS, EREC, CCEN, CCLA, SAFC, ID3ERR LOCK, BUIL, LHEA, LTAI, DETA, SHOP, LSTR

D:6

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

CHARACTER*(*) CHARACTER*(*) CHARACTER*(*) REAL REAL

TYPE, NAME, FLOW, MATR FLUR, CASR, DSCO, PTSP

OWNE, PSPE,

LNTP, ISPE,

HCON, TSPE,

TCON, DUTY,

INSC, HSTU, HREF, TREF HBOR, TBOR, TEMP, PRES, HPOS(3), HDIR(3) 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 TYPE OWNE BUIL LTAI SHOP LNTP HBOR HCON TEMP FLOW FLUR PSPE TSPE CCLA DSCO INSC HSTU HREF TREF HDIR TDIR Display flag Type Owner name/ref Built flag Tail flag Shop flag Line type identifier Head bore Head connection type Temperature Flow direction Fluid ref Pipe spec Tracing spec Cost class Design code Inspection schedule Tube spec ref Head ref Tail ref Head direction Tail direction HPOS TPOS ID3ERR Head position Tail position Error code NAME LOCK LHEA DETA LSTR EREC TBOR TCON PRES MATR CASR ISPE CCEN DUTY PTSP SAFC Name Lock flag Head flag Detailed flag Stressed flag Erection Tail bore Tail connection type Pressure Material ref List of cases ref Insulation spec Cost centre Duty Paint spec Safety class

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 LOGICAL CHARACTER*(*) CHARACTER*(*) REAL

ID3DIS, CCEN, CCLA, EREC, SAFC, ID3ERR LOCK, BUIL, SHOP TYPE, NAME, MATR, FLUR OWNE, PSPE, ISPE, TSPE,

CASR, DUTY, LNTP, DSCO, PTSP, INSC TEMP, PRES

Performs the equivalent of a Q ATT for the current element for the attributes common to branch and pipe. Calls D3QCMA, D3RLOG, D3RREA, D3RNAM, D3RINT, D3RTEX, D3RWOR, D3XLEN, D3EMSG Called by D3QBRA, D3QPIP Arguments: as defined in D3QBRA, D3QPIP 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 LOGICAL CHARACTER*(*) REAL

ID3DIS, ARRI, LEAV, ID3ERR LOCK, SHOP, BUIL, ORIL, POSI, LOFF TYPE, NAME, OWNE, SPRE, LSTU, CREF, ISPE, TSPE 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 TYPE OWNE POS SPRE CREF LEAV HEIG BUIL Display flag Type Owner name/ref Position Spec ref Connection ref Leave PPoint Height Built flag NAME LOCK ORI LSTU ARRI ANGL RADI SHOP Name Lock flag Orientation Tube ref Arrive PPoint Angle Radius Shop flag

D:8

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

ORIL LOFF TSPE

Orientation flag Offline flag Tracing spec

POSI ISPE ID3ERR

Position flag Insulation spec 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 LOGICAL CHARACTER*(*) REAL

ID3DIS, ARRI, LEAV, ID3ERR LOCK, SHOP, BUIL, ORIL, POSI TYPE, NAME, OWNE, SPRE, LSTU, CREF, ISPE, TSPE POS(3), ORI(3), RADI, ANGL

Performs the equivalent of a Q ATT for an ELBO. Calls D3RNAM, D3XLEN, D3QCPA, D3RREA, D3EMSG, D3ERST ID3DIS TYPE OWNE POS SPRE CREF LEAV RADI SHOP POSI TSPE Display flag Type Owner name/ref Position Spec ref Connection ref Leave PPoint Radius Shop flag Position flag Tracing spec NAME LOCK ORI LSTU ARRI ANGL BUIL ORIL ISPE ID3ERR Name Lock flag Orientation Tube ref Arrive PPoint Angle Built flag Orientation flag Insulation spec Error code

SUBROUTINE D3QCPA( ID3DIS, TYPE, NAME, OWNE, LOCK, POS, ORI, SPRE, LSTU, ARRI, LEAV, BUIL, SHOP, ORIL, POSI, ISPE, TSPE, ID3ERR )

INTEGER LOGICAL CHARACTER*(*) REAL

ID3DIS, ARRI, LEAV, ID3ERR LOCK, BUIL, SHOP, ORIL, POSI TYPE, NAME, OWNE, SPRE, LSTU, ISPE, TSPE 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 LOGICAL CHARACTER*(*) REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, FUNC, DSCO, PTSP, INSC, ISPE POS(3), ORI(3)

Performs the equivalent of a Q ATT for an EQUI. Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RRA, D3EMSG ID3DIS TYPE OWNE FUNC PTSP POS ISPE ID3ERR Display flag Type Owner name/ref Function Paint spec Position Insulation schedule Error code NAME LOCK DSCO INSC ORI Name Lock flag Design code Inspection schedule Orientation

SUBROUTINE D3QNOZ( ID3DIS, TYPE, NAME, OWNE, LOCK, TEMP, PRES, POS, ORI, CREF, CATR, ANGL, HEIG, RADI, DUTY, ISPE, ID3ERR )

INTEGER LOGICAL CHARACTER*(*) REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, CREF, CATR, DUTY, ISPE 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 TYPE OWNE TEMP POS CREF ANGL RADI ISPE Display flag Type Owner name/ref Temperature Position Connection ref Angle Radius Insulation spec NAME LOCK PRES ORI CATR HEIG DUTY ID3ERR Name Lock flag Pressure Orientation Catalogue ref Height Duty Error code

SUBROUTINE D3QBOX( ID3DIS, TYPE, NAME, OWNE, LOCK, XLEN, YLEN, ZLEN, POS, ORI, LEVE, OBST, ID3ERR )

INTEGER LOGICAL CHARACTER*(*) REAL

ID3DIS, LEVE(2), OBST, ID3ERR LOCK TYPE, NAME, OWNE 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 TYPE OWNE XLEN ZLEN ORI OBST Display flag Type Owner name/ref X length Z length Orientation Obstruction level NAME LOCK YLEN POS LEVE ID3ERR Name Lock flag Y length Position Drawing level 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 TYPE OWNE ID3ERR Display flag Type Owner name/ref Error code NAME LOCK Name Lock flag

SUBROUTINE D3QSEC( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE

Performs the equivalent of a Q ATT for an SECT. Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG ID3DIS TYPE OWNE ID3ERR Display flag Type Owner name/ref Error code NAME LOCK Name Lock flag

SUBROUTINE D3QCOM( ID3DIS, TYPE, NAME, OWNE, LOCK, GTYP, PTRE, GMRE, ID3NIN, PARA, PARWOR, ID3NOU, ID3ERR ) INTEGER ID3DIS, ID3NIN, ID3NOU, ID3ERR

LOGICAL CHARACTER*(*) CHARACTER*(*) REAL

LOCK TYPE, NAME, OWNE, GTYP, PTRE, GMRE PARWOR(ID3NIN) PARA(ID3NIN)

Performs the equivalent of a Q ATT for a SCOMP Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3RRA, D3UDEH, D3EMSG, D3ERST ID3DIS ID3NIN TYPE OWNE GTYP GMRE Display flag Max number of elements for PARA array Type Owner name/ref Generic type Geometry set ref NAME LOCK PTRE PARA Name Lock flag Point set ref Parameters array

D:12

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

PARWOR ID3NOU ID3ERR

Array of dehashed word parameters Number of elements returned in PARA array Error code

SUBROUTINE D3QUNI( ID3DIS, TYPE, NAME, OWNE, LOCK, BUNI, DUNI, DFUN, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, BUNI, DUNI, DFUN

Performs the equivalent of a Q ATT for a UNIT. Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3EMSG, D3ERST ID3DIS TYPE OWNE BUNI DFUN Display flag Type Owner name/ref Bore units Defined units NAME LOCK DUNI ID3ERR Name Lock flag Distance units Error code

SUBROUTINE D3QUSE( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE

Performs the equivalent of a Q ATT for an USEC. Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG ID3DIS TYPE OWNE ID3ERR Display flag Type Owner name/ref Error code NAME LOCK Name Lock flag

SUBROUTINE D3QUDE( ID3DIS, TYPE, NAME, OWNE, LOCK, ABRE, ADEN, MULT, SIGF, DECP, ID3ERR )

INTEGER LOGICAL

ID3DIS, SIGF, DECP, ID3ERR LOCK

D:13

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

CHARACTER*(*) REAL ADEN, MULT

TYPE, NAME, OWNE, ABRE

Performs the equivalent of a Q ATT for a UDEF. Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RREA, D3RINT, D3EMSG ID3DIS TYPE OWNE ABRE MULT DECP Display flag Type Owner name/ref Abbreviation Multiplier Decimal places NAME LOCK ADEN SIGF ID3ERR Name Lock flag Adend Significant figures Error code

SUBROUTINE D3QMSE( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE

Performs the equivalent of a Q ATT for an MSET. Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG ID3DIS TYPE OWNE ID3ERR Display flag Type Owner name/ref Error code NAME LOCK Name Lock flag

SUBROUTINE D3QMTY( ID3DIS, TYPE, NAME, OWNE, LOCK, UREF, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, UREF

Performs the equivalent of a Q ATT for an MTYP. Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG, D3ERST ID3DIS TYPE Display flag Type NAME Name

D:14

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

OWNE UREF

Owner name/ref Units reference

LOCK ID3ERR

Lock flag Error code

SUBROUTINE D3QATL( ID3DIS, TYPE, NAME, OWNE, LOCK, ATNA, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, ATNA

Performs the equivalent of a Q ATT for an ATLI. Calls D3RNAM, D3XLEN, D3QCMA, D3RWOR, D3EMSG, D3ERST D3DIS TYPE OWNE ATNA Display flag Type Owner name/ref Atname NAME LOCK ID3ERR Name Lock flag Error code

ISUBROUTINE D3QSPW( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE

Performs the equivalent of a Q ATT for an SPWL. Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG ID3DIS TYPE OWNE ID3ERR Display flag Type Owner name/ref Error code NAME LOCK Name Lock flag

SUBROUTINE D3QSPE( ID3DIS, TYPE, NAME, OWNE, LOCK, QUAL, QUES, DEFA, TDEFA, MATR, FLUR, RATI, LNTP, ID3ERR )

INTEGER LOGICAL CHARACTER*(*) REAL RATI. DEFA

ID3DIS, QUAL, ID3ERR LOCK TYPE, NAME, OWNE, QUES, TDEFA, MATR, FLUR, LNTP

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 TYPE OWNE QUAL DEFA MATR RATI ID3ERR Display flag Type Owner name/ref Quality Default Material ref Pressure rating Error code NAME LOCK QUES TDEFA FLUR LNTP Name Lock flag Question Text default Fluid ref Line type

SUBROUTINE D3QSEL( ID3DIS, TYPE, NAME, OWNE, LOCK, QUAL, QUES, ANSW, TANSW, MAXA, DEFA, TDEFA, ID3ERR )

INTEGER LOGICAL CHARACTER*(*) REAL

ID3DIS, QUAL, ID3ERR LOCK TYPE, NAME, OWNE, QUES, TANSW, TDEFA ANSW, MAXA, DEFA

Performs the equivalent of a Q ATT for a SELE. Calls D3RNAM, D3XLEN, D3QCMA, D3RINT, D3RWOR, D3EMSG, D3RREA, D3ERST, D3RTEX ID3DIS TYPE OWNE QUAL ANSW MAXA TDEFA Display flag Type Owner name/ref Quality Answer Maxan Text default NAME LOCK QUES TANSW DEFA ID3ERR Name Lock flag Question Text answer Default Error code

SUBROUTINE D3QSPC( ID3DIS, TYPE, NAME, OWNE, LOCK, ANSW, MAXA, TANSW, CATR, CMPR, BLTR, DETR, MATX, ID3ERR )

INTEGER LOGICAL

ID3DIS, ID3ERR LOCK

D:16

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

CHARACTER*(*) CHARACTER*(*) REAL

TYPE, NAME, OWNE, TANSW, CATR, CMPR, BLTR, DETR MATX ANSW, MAXA

Performs the equivalent of a Q ATT for a SPCO. Calls D3RNAM, D3XLEN, D3QCMA, D3RREA, D3EMSG, D3ERST, D3RTEX ID3DIS TYPE OWNE ANSW TANSW CMPR DETR ID3ERR Display flag Type Owner name/ref Answer Text answer Component ref Detail text ref Error code NAME LOCK MAXA CATR BLTR MATX Name Lock flag Maxan Catalogue ref Bolt ref Material text ref

SUBROUTINE D3QCCT( ID3DIS, TYPE, NAME, OWNE, LOCK, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE

Performs the equivalent of a Q ATT for a CCTA. Calls D3RNAM, D3XLEN, D3QCMA, D3EMSG ID3DIS TYPE OWNE ID3ERR Display flag Type Owner name/ref Error code NAME LOCK Name Lock flag

SUBROUTINE D3QCOC( ID3DIS, TYPE, NAME, OWNE, LOCK, CTYP, ID3ERR )

INTEGER LOGICAL CHARACTER*(*)

ID3DIS, ID3ERR LOCK 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 TYPE OWNE CTYP Display flag Type Owner name/ref Connection type array NAME LOCK ID3ERR Name Lock flag 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 LOGICAL CHARACTER*(*) REAL REAL REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, MRKR OUTD, ACBO, BTOL, WTOL, WDIA, SHAP, RINE(3) SIF(3), PRFC, SDTH(3), CORA, EFAC, PWAS, BFLE UWEI, UIWE

Performs the equivalent of a Q ATT for a TUBD. Calls D3RNAM, D3XLEN, D3QCDA, D3RREA, D3EMSG ID3DIS TYPE OWNE OUTD BTOL UWEI WDIA RINE PRFC CORA PWAS BFLE MRKR Display flag Type Owner name/ref Outside diameter Bore tolerance Unit pipe weight Wind diameter modulus Rotational inertia Pressure factor Corrosion thickness Percentage waste factor Out of plane flexibility factor for bends 3 way component marker ID3ERR Error code NAME LOCK ACBO WTOL UIWE SHAP SIF SDTH EFAC Name Lock flag Actual bore Wall thickness tolerance Unit insulation weight Shape modulus Stress intensity factor Saddle thickness E-factor

D:18

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 LOGICAL CHARACTER*(*) REAL REAL REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, MRKR OUTD, ACBO, BTOL, WTOL, WDIA, SHAP, RINE(3), SIF(3), PRFC SDTH(3), CORA, EFAC, PWAS, BFLE, CWEI, CIWE, DFFL(6) DMFL(9), RMFL(6)

Performs the equivalent of a Q ATT for a CMPD. Calls D3RNAM, D3XLEN, D3QCDA, D3RREA, D3RRA, D3EMSG ID3DIS TYPE OWNE OUTD BTOL CWEI WDIA RINE PRFC CORA PWAS BFLE Display flag Type Owner name/ref Outside diameter Bore tolerance Total component weight Wind diameter modulus Rotational inertia Pressure factor Corrosion thickness Percentage waste factor Out of plane flexibility factor for bends NAME LOCK ACBO WTOL CIWE SHAP SIF SDTH EFAC Name Lock flag Actual bore Wall thickness tolerance Total insulation weight Shape modulus Stress intensity factor Saddle thickness E-factor

Next three are parts of flexibility matrix for component DFFL RMFL MRKR Displacement force Rotation moment 3 way component marker ID3ERR Error code DMFL Displacement moment

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 LOGICAL CHARACTER*(*) REAL REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, MRKR OUTD, ACBO, BTOL, WTOL, WDIA, SHAP, RINE(3) 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 LOGICAL CHARACTER*(*) REAL REAL REAL

ID3DIS, ID3ERR LOCK TYPE, NAME, OWNE, APPL FORC(3), MOME(3), DISP(3), ROTN(3), DLIM(6) RLIM(6), FLIM(3), MLIM(3), DFLF(3), RFLF(3) FCOE(3), CPUL(3), CPUT(3)

Performs the equivalent of a Q ATT for a CONS. Calls D3RNAM, D3XLEN, D3QCMA, D3RTEX, D3RRA, D3EMSG ID3DIS TYPE OWNE APPL MOME ROTN RLIM Display flag Type Owner name/ref Application Moment Rotation Rotation limits NAME LOCK FORC DISP DLIM FLIM Name Lock flag Force Displacement Displacement limits Force limits

D:20

12.0

Data Access Routines User Guide

Auxiliary Subroutine Library

MLIM RFLF FCOE CPUT

Moment limits Rotational flexibility factors Friction coefficient Cold twist

DFLF

Linear flexibility factors

CPUL ID3ERR

Cold pull 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 INTEGER LOGICAL CHARACTER*(*) CHARACTER*(*)

ID3DIS, ID3ERR, UKEY, ABLE, ULEN, MAXE, OUTE MAXR, OUTR LOCK TYPE, NAME, OWNE, UDNA, UTYP, DFLT, RPTX, DESC 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 MAXR TYPE OWNE UKEY ABLE ULEN DFLT DESC ELEL OUTE OUTR ID3ERR Display flag Size of REFL array Type Owner name/ref UDA key Min. abbrev. of UDNA NAME LOCK UDNA UTYP Name Lock flag UDA name (without :) UDA type MAXE Size of ELEL array

No. of values if an array or maximum length if TEXT or WORD Default value as text Description Element list No. of elements returned in ELEL No. of elements returned in REFL Error code RPTX UUNI REFL REPORTER text UNITs Reference list

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 D3XLEN Character string Significant length of CD3STR (min 1)

D:22

12.0

Data Access Routines User Guide

Multibyte Text Handling

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: D3RNAM: D3RTEX: D3RPTX: D3RPAT: in the CD3NAM (element name) input argument in the CD3NAM (element name) return argument in the CD3TEX (text attribute) return argument in the CD3RPT (REPORTER text) return argument 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 : FECS-OUT sequence : '&~' '&' (ISO 2/6, ISO 7/14) '(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 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 C C Function to translate FECs string (machine-specific in parts) Program to read, translate and print FECs text

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 C Not already multibyte 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 + C .AND. STRING(IPOS:IPOSP1) .EQ. ' &') THEN 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 C Multibyte portion of text string and not FECOUT Convert to ASCII, convert back add 128 to ASCII value, =

FECS(OPOS:OPOS) CHAR(ICHAR(STRING(IPOS:IPOS)) + 128) 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

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

FECs translation test

CHARACTER*50 CHARACTER*120 CHARACTER*1 C

NAME, FECS, NAME3, CNAME, CNAME3 TEXT CDUM

Optional declarations INTEGER EXTERNAL EXTERNAL IERR, IPOS D3INIT, D3ERST, D3RTEX, D3RNAM D3EMSG, D3MNUM, FECS, FECST D3MMDB, D3FIN, D3MNAM, D3FEND,

Project entry CALL D3INIT( 'FEC', 'SYSTEM', 'XXXXXX', 'NONE', ' ', IERR ) IF (IERR.NE.0) GOTO 9000

MDB Selection CALL D3MMDB ( 'DES/|}~', ' ', IERR ) IF ( IERR .NE. 0 ) GOTO 9000

Go to zone CALL D3MNAM('/ZONE1.EQUIP', IERR) IF ( IERR .NE. 0 ) GOTO 9000

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

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 9000 Exit 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*(*) CHARACTER*12 CHARACTER*1 INTEGER NAME 0 TEXT, FECS, CTEXT CDUM D3ULEN, IERR

E:7

12.0

Data Access Routines User Guide

Multibyte Text Handling

EXTERNAL C C

D3ULEN, D3RTEX

FECS,

D3EMSG,

D3ERST,

CALL D3RTEX(NAME, TEXT, IERR) 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*, ' RETURN END ', NAME, ': ', CTEXT(:D3ULEN(CTEXT))

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

C/C++ Library
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. ** ** ** ** ** ** ** ** ** **/ Notes: 1. arguments are passed by address. header file for DARS C to FORTRAN interface. The DAR routines are written in FORTRAN but here is the user C/C++ interface d3libc.h

#ifndef D3LIBC_H #define D3LIBC_H

/* end of system includes */ #include <pdms.h>

/* ** DAR interface function/subroutine prototypes */

#ifdef __cplusplus

extern "C" void d3echk extern "C" void d3emsg

( char *cd3err ) ; ( int *id3err, int *ld3dis, DARS_MESS cd3msg ) ;

extern "C" void d3erst extern "C" void d3fend extern "C" void d3fin

( void ) ; ( void ) ; ( 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 ) ; ( char *cd3nam, int *id3pos, int *id3err ) ; ( char *cd3nam, int *id3err ) ; ( char *cd3nm1, char *cd3nm2, int *id3err ) ; ( char *cd3mdb, char *cd3wrk, int *id3err ) ; ( char *cd3nam, int *id3err ) ; ( char *cd3typ, int *id3lis, int *id3err ) ; ( int *id3err ) ; ( int *id3pos, PDMS_DBNAME cd3nam, PDMS_WORD cd3typ, int *id3sta, int *id3err ) ; ( char *cd3pos, char *cd3typ, int *id3err ) ; ( int *id3err ) ; ( int *id3err ) ; ( PDMS_WORD cd3bun, PDMS_WORD cd3dun, int *id3err ) ; ( int *ld3tub, float *rd3box, int *id3err ) ; ( int *id3dat, DARS_RDAT cd3dat, int *id3err ) ; ( char *cd3att, int *id3nin, int *id3ia, int *id3nou, int *id3err ) ; ( char *cd3att, int *id3int, int *id3err ) ; ( char *cd3att, int *id3nin, int *ld3la, int *id3nou, int *id3err ) ; ( char *cd3att, int *ld3log, int *id3err ) ; ( char *cd3att, PDMS_NAME cd3nam, int *id3err ) ;

extern "C" void d3mcdb extern "C" void d3mddb extern "C" void d3medb extern "C" void d3mmdb extern "C" void d3mnam extern "C" void d3mnum extern "C" void d3mown extern "C" void d3mqdb

extern "C" void d3mrel extern "C" void d3mrst extern "C" void d3msav extern "C" void d3rbdu extern "C" void d3rbox extern "C" void d3rdat extern "C" void d3ria

extern "C" void d3rint extern "C" void d3rla

extern "C" void d3rlog extern "C" void d3rnam

F:4

12.0

Data Access Routines User Guide

C/C++ Library

extern "C" void d3rorl extern "C" void d3rpat

( char *cd3crd, float *rd3ori, int *id3err ) ; ( char *cd3poi, char *cd3crd, float *rd3pos, float *rd3dir, float *rd3bor, PDMS_WORD cd3con, int *id3err ) ; ( char *cd3nam, PDMS_TEXT cd3tex, int *id3err ) ; ( char *cd3crd, float *rd3pos, int *id3err ) ; ( char *cd3att, PDMS_RPTX cd3rpt, int *id3err ) ; ( char *cd3att, int *id3nin, float *rd3ra, int *id3nou, int *id3err ) ; ( char *cd3att, float *rd3rea, int *id3err ) ; ( char *cd3att, PDMS_NAME cd3ref, int *id3err ) ; ( char *cd3att, int *id3nin, PDMS_NAME cd3rfa[], int *id3nou, int *id3err ) ; ( char *cd3att, PDMS_TEXT cd3tex, int *id3err ) ; ( PDMS_WORD cd3typ, int *id3err ) ; ( char *cd3typ, int *id3max, PDMS_UDNA cd3nms[], int *id3abv, PDMS_WORD cd3atp[], int *id3num, int *id3err ) ; ( char *cd3att, PDMS_UUNI cd3unt, int *id3err ) ; ( char *cd3att, int *id3nin, PDMS_WORD cd3wa[], int *id3nou, int *id3err ) ; ( char *cd3att, PDMS_WORD cd3wor, int *id3err ) ; ( int *id3uni ) ;

extern "C" void d3rprj extern "C" void d3rprl extern "C" void d3rptx extern "C" void d3rra

extern "C" void d3rrea extern "C" void d3rref extern "C" void d3rrfa

extern "C" void d3rtex extern "C" void d3rtyp extern "C" void d3ruda

extern "C" void d3runi extern "C" void d3rwa

extern "C" void d3rwor extern "C" int d3uclu /*

** 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 ) ; ( int *id3int, PDMS_WORD cd3wor ) ; ( int *id3dat, DARS_RDAT cd3dat ) ; ( int *id3uni ) ; ( int *ready ) ; ( char *cd3dat, int *id3err ) ; ( char *cd3str ) ; ( char *cd3mon ) ;

extern "C" void d3udeh extern "C" void d3udtm extern "C" int d3ugtu extern "C" void d3uini extern "C" int d3ulds extern "C" int d3ulen extern "C" void d3umon

#else /* C rather than C++ */

void d3echk void d3emsg void d3erst void d3fend void d3fin void d3init

( char *cd3err ) ; ( int *id3err, int *ld3dis, DARS_MESS cd3msg ) ; ( void ) ; ( void ) ; ( int *id3err ) ; ( char *cd3prj, char *cd3usr, char *cd3pas, char *cd3mon, char *cd3wrk, int *id3err ) ; ( char *cd3nam, int *id3pos, int *id3err ) ; ( char *cd3nam, int *id3err ) ; ( char *cd3nm1, char *cd3nm2, int *id3err ) ; ( char *cd3mdb, char *cd3wrk, int *id3err ) ;

void d3mcdb void d3mddb void d3medb void d3mmdb

F:6

12.0

Data Access Routines User Guide

C/C++ Library

void d3mnam void d3mnum void d3mown void d3mqdb

( char *cd3nam, int *id3err ) ; ( char *cd3typ, int *id3lis, int *id3err ) ; ( int *id3err ) ; ( int *id3pos, PDMS_DBNAME cd3nam, PDMS_WORD cd3typ, int *id3sta, int *id3err ) ; ( char *cd3pos, char *cd3typ, int *id3err ) ; ( int *id3err ) ; ( int *id3err ) ; ( PDMS_WORD cd3bun, PDMS_WORD cd3dun, int *id3err ) ; ( int *ld3tub, float *rd3box, int *id3err ) ; ( int *id3dat, DARS_RDAT cd3dat, int *id3err ) ; ( char *cd3att, int *id3nin, int *id3ia, int *id3nou, int *id3err ) ; ( char *cd3att, int *id3int, int *id3err ) ; ( char *cd3att, int *id3nin, int *ld3la, int *id3nou, int *id3err ) ; ( char *cd3att, int *ld3log, int *id3err ) ; ( char *cd3att, PDMS_NAME cd3nam, int *id3err ) ; ( char *cd3crd, float *rd3ori, int *id3err ) ; ( char *cd3poi, char *cd3crd, float *rd3pos, float *rd3dir, float *rd3bor, PDMS_WORD cd3con, int *id3err ) ; ( char *cd3nam, PDMS_TEXT cd3tex, int *id3err ) ; ( char *cd3crd, float *rd3pos, int *id3err ) ;

void d3mrel void d3mrst void d3msav void d3rbdu void d3rbox void d3rdat void d3ria

void d3rint void d3rla

void d3rlog void d3rnam void d3rorl void d3rpat

void d3rprj void d3rprl

F:7

12.0

Data Access Routines User Guide

C/C++ Library

void d3rptx void d3rra

( char *cd3att, PDMS_RPTX cd3rpt, int *id3err ) ; ( char *cd3att, int *id3nin, float *rd3ra, int *id3nou, int *id3err ) ; ( char *cd3att, float *rd3rea, int *id3err ) ; ( char *cd3att, PDMS_NAME cd3ref, int *id3err ) ; ( char *cd3att, int *id3nin, PDMS_NAME cd3rfa[], int *id3nou, int *id3err ) ; ( char *cd3att, PDMS_TEXT cd3tex, int *id3err ) ; ( PDMS_WORD cd3typ, int *id3err ) ; ( char *cd3typ, int *id3max, PDMS_UDNA cd3nms[], int *id3abv, PDMS_WORD cd3atp[], int *id3num, int *id3err ) ; ( char *cd3att, PDMS_UUNI cd3unt, int *id3err ) ; ( char *cd3att, int *id3nin, PDMS_WORD cd3wa[], int *id3nou, int *id3err ) ; ( char *cd3att, PDMS_WORD cd3wor, int *id3err ) ; ( int *id3uni ) ;

void d3rrea void d3rref void d3rrfa

void d3rtex void d3rtyp void d3ruda

void d3runi void d3rwa

void d3rwor int d3uclu /*

** 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 void d3udtm int d3ugtu void d3uini int d3ulds int d3ulen void d3umon

( int *id3int, PDMS_WORD cd3wor ) ; ( int *id3dat, DARS_RDAT cd3dat ) ; ( int *id3uni ) ; ( int *ready ) ; ( char *cd3dat, int *id3err ) ; ( char *cd3str ) ; ( 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.

/* ** ** ** ** ** ** ** ** ** */ 1. Strings are defined as being 1 more than in FORTRAN to account for the C string terminator '\0'. Notes: Header file to define some system constants. pdms.h

#ifndef PDMSH

#define PDMSH

F:9

12.0

Data Access Routines User Guide

C/C++ Library

/* Some constants */ #define #define #define #define #define #define #define #define #define #define #define #define typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef #endif TRUE FALSE PDMSNAMELEN PDMSUDNANAMELEN PDMSWORDLEN PDMSTEXTLEN PDMSRPTXTEXTLEN PDMSUUNITEXTLEN DARSMESSTEXTLEN DARSRDATTEXTLEN DARSCERRTEXTLEN PDMSDBNAMELEN char char char char char char char char char char int PDMSNAME PDMSWORD PDMSTEXT PDMSRPTX PDMSUDNA PDMSUUNI DARSMESS DARSRDAT DARSCERR PDMSDBNAME LOGICAL ; 64 [ PDMSNAMELEN + 1 ] ; [ PDMSWORDLEN + 1 ] ; [ PDMSTEXTLEN + 1 ] ; [ PDMSRPTXTEXTLEN + 1 ] ; [ PDMSUDNANAMELEN + 1 ] ; [ PDMSUUNITEXTLEN + 1 ] ; [ DARSMESSTEXTLEN + 1 ] ; [ DARSRDATTEXTLEN + 1 ] ; [ DARSCERRTEXTLEN + 1 ] ; [ PDMSDBNAMELEN + 1 ] ; 6 1000 20 20 50 20 3 50 13 1 0

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

C
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

G
General Utility Routines . . . . . . . . . . . . . 5:5

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

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

N
Navigation Routines . . . . . . . . . . . . . . . . 5:1

P
PDMS Data Access . . . . . . . . . . . . . . . . PDMS Database Organisation . . . . . . . . PDMS Database Security . . . . . . . . . . . Program Debugging . . . . . . . . . . . . A:4, Program Running . . . . . . . . . . . . . . A:4, 3:1 3:1 3:1 F:1 F:1

E
Error Codes . . . . . . . . . . . . . . . . . . . . . . .C:1 Error Handling . . . . . . . . . . . . . . . . . . . . . 2:3

Index page 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