This document was uploaded by user and they confirmed that they have the permission to share
it. If you are author or own the copyright of this book, please report to us by using this DMCA
report form. Report DMCA
Overview
Download & View Administrator Command Reference Manual as PDF for free.
Disclaimer 1.1 AVEVA does not warrant that the use of the AVEVA software will be uninterrupted, error-free or free from viruses. 1.2 AVEVA shall not be liable for: loss of profits; loss of business; depletion of goodwill and/or similar losses; loss of anticipated savings; loss of goods; loss of contract; loss of use; loss or corruption of data or information; any special, indirect, consequential or pure economic loss, costs, damages, charges or expenses which may be suffered by the user, including any loss suffered by the user resulting from the inaccuracy or invalidity of any data created by the AVEVA software, irrespective of whether such losses are suffered directly or indirectly, or arise in contract, tort (including negligence) or otherwise. 1.3 AVEVA's total liability in contract, tort (including negligence), or otherwise, arising in connection with the performance of the AVEVA software shall be limited to 100% of the licence fees paid in the year in which the user's claim is brought. 1.4 Clauses 1.1 to 1.3 shall apply to the fullest extent permissible at law. 1.5 In the event of any conflict between the above clauses and the analogous clauses in the software licence under which the AVEVA software was purchased, the clauses in the software licence shall take precedence.
Trademark AVEVA and Tribon are registered trademarks of AVEVA Solutions Limited or its subsidiaries. Unauthorised use of the AVEVA or Tribon trademarks is strictly forbidden. AVEVA product/software names are trademarks or registered trademarks of AVEVA Solutions Limited or its subsidiaries, registered in the UK, Europe and other countries (worldwide). The copyright, trademark rights, or other intellectual property rights in any other product or software, its name or logo belongs to its respective owner.
Administrator Command Reference Manual
Revision Sheet
Date
Version
September 2011 12.1.1
Comments / Remarks Linewidths example added under Query section. Dabacon Buffer Size section incorporated.
Introduction This manual describes the PDMS Administration commands for Standard (non-global) and Global projects. It is written for System Administrators who are already experienced administration users and who wish to write macros or use command input, rather than the GUI. The content of this manual is based on the assumption that you are already familiar with the concepts that a PDMS System Administrator needs to understand. If you are not familiar with these concepts, you should refer to the relevant user guide, as follows: •
Using PDMS Administration for a standard (non-global) project is described in the Administrator User Guide, which tells you how to set up and administer PDMS projects using the GUI. The User Guide also describes the concepts that PDMS System Administrators need to understand.
•
Using Plant Design Global via the GUI is described in the Global User Guide, which also describes the concepts in Plant Design Global that PDMS System Administrators need to understand.
Within the manual, commands that are only available in AVEVA Global are labelled as Global Project Administration Commands. Some of these commands are only available at the Hub of a Global Project, and this is also shown. Some options in standard commands are only available in Global Projects and these options are also indicated by 'Global' in associated text. This manual also describes how to use DICE, the PDMS Data Integrity Checker, outside PDMS, as there is no GUI for the stand-alone module. It also describes database reconfiguration, which is also a command line or macro operation.
1.1
Macros Most people who read this manual will be writing macros, either to run into PDMS when required, for example, to create a new project, or as part of customising the ADMIN interface. There are some commands in ADMIN which automatically create simple PDMS macros. These are command files which can be read back into PDMS. In particular, you can use the REPLICATE command to create a macro which will replicate a project. For information about writing more complicated macros using the PDMS Programmable Macro Language, (PML), see the Software Customisation Guide and the Software Customisation Reference Manual.
applies to Standard and Global projects and describes how to run the PDMS Data Integrity Checker, DICE, from outside PDMS. This chapter is included in the Command Reference manual as there is no interface to stand-alone DICE, and you will need to enter commands interactively or via a macro.
Reconfiguration,
applies to Standard and Global projects and describes database reconfiguration.
System and Projects
Global
applies to Standard and Global projects. It contains maps of the System Database and Global Database Hierarchies, and a list of the ADMIN elements and their attributes that can be set explicitly by the user.
Transaction Database
applies to Global projects only, and describes the transaction database, the elements in it, and their attributes.
Command Summary
applies to Standard and Global projects. It lists the ADMIN commands in functional groups.
Command Details
applies to Standard and Global projects. It occupies the majority of the manual and describes every ADMIN command. The descriptions appear in alphabetical order of command names.
Dabacon Buffer Size
specifies buffer requirements for running a project.
Drawing File and Folders
file name conventions used for Drawing and Picture files during propagation.
Stand-Alone DICE The Data Integrity Checker (DICE) can be run as a stand-alone program outside PDMS. This may be necessary if the System database has been corrupted, and you cannot enter PDMS. Stand-alone DICE is started up using the script named dop, supplied in the PDMSEXE directory. Give the following command, outside PDMS:
$PDMSEXE/dop For a summary of the commands that you can use in DICE, see the Data Integrity Checking commands in Command Summary. Commands to exit from DICE in stand-alone mode are:
STOP FINISH You can send the reports generated by DICE to a named file in your working directory using the ALPHA command.
2.1
DICE Errors PDMS obtains the text of all its user messages from an external file. When DICE is used from within a PDMS project, this file is automatically available, but this is not the case in stand-alone mode. Hence the next command you must give in stand-alone mode is the ERRORFILE command, followed by the name of the error message file. For example:
ERRORFILE /%PDMSEXE%/MESSAGE.DAT Note: This file will contain error messages referring to the operation of DICE itself, not any errors DICE has found during the checking process The default name of the message file can be found from the entry for DICE in the current version of makmac.mac, the project configuration macro.
2.2
DICE Commands Set up the options you require using the following commands (see the appropriate command pages for details): •
You can send the reports generated by DICE to a named file using the ALPHA command. You can check one or more DB files by using the CHECK command. In this mode, you can only refer to databases by their external filenames rather than by their internal PDMS DB names. Up to ten files may be specified in a single command. Note: The EXTERNAL command cannot be used in stand-alone mode (or by REMOTE CHECK), because only one DB file can be accessed at a time.
Reconfiguration PDMS RECONFIGURER is run from within ADMIN, but only by using the command line. In order to understand why database reconfiguration may be necessary, and to appreciate the steps involved, it is helpful to have some knowledge of PDMS database structures and their management. For a summary of this information, including an explanation of DDLs (Database Description Languages) and DABACON (the DAtaBAse CONtrol program), read the chapter Database Management System in the Administrator User Guide.
3.1
Reconfiguration Process Reconfiguration is a two-pass operation, acting on either a complete database or on specified parts of one. In the first pass, RECONFIGURER scans a named source database and copies the data for some or all existing elements and their attributes into intermediate files. In the second pass, the contents of the intermediate files are transferred to a specified destination database. This mode of operation has the following features: •
Only existing elements are copied to the intermediate files; deleted items and corrupt data are ignored. The destination database created from these files is therefore both compact and uncorrupted.
•
The reference and non-reference attributes of the elements are held in different intermediate files. The method of transfer of data to the destination database ensures that all referencing is complete and consistent.
•
The source and destination databases may have different DDLs. This enables existing data to be restructured to conform to a new database structure and so, for example, to be used with a new version of PDMS.
•
Reconfiguration can used to transfer a project to different hardware. The intermediate files produced by the first stage can be decoded into a portable format (typically ASCII), and transferred, and then the second stage carried out.
A similar technique is used to convert whole projects to new versions of PDMS, though in this case the intermediate files need not be decoded.
3.2
Starting up RECONFIGURER Enter PDMS in non-graphics (tty) mode by typing:
pdms tty Then specify the Project and User ID/Password, and enter ADMIN. For example:
proj ABC user SYSTEM/XXXXXX admin You can now start to set up the reconfiguration parameters using the commands summarised in the Command Summary under Reconfiguration.
3.3
Administrative and Querying Commands Some of the general PDMS and querying commands, which are particularly relevant to reconfiguration, are summarised below. SYSTAT
Gives information about the current active status of the project within which you are working.
LIST
Lists project information; there are a variety of options.
SET TEAM
Sets the specified team as the current one.
LOCK, UNLOCK
Locking the System Database prevents any new users entering the project.
MESSAGE
Sends messages to other users.
Q DB
Gives the type, number and filename of the specified DB and a list of the MDBs of which it is a member. For example:
Q DB CIVIL/JBX37C CIVIL/ JBX37C DESI NUMBER 6 TVX000/TVX009 MDBS: /LAYOUT /TANKS Q COPIES
FILENAME /
Lists all DBs which are copies of the specified DB. For example:
Q COPIES CIVIL/JBX37C DB CIVIL/JBX37C HAS COPIES: CIVILl/JBX47C Q MDB
Lists the DBs in the specified MDB.
Q TEAM
Lists the users who are members of the specified team plus a list of the DBs owned by the team.
Q SET TEAM
Gives the name of the currently set team if any.
Q LOCK
Shows whether the project is locked.
3.4
Basic Reconfiguration
3.4.1
Reconfiguring a Single Database The simplest reconfiguration involves a single DB which has no references into it from other DBs; for example, a Design DB which has no associated Drawing (PADD) DBs. A simple reconfiguration requires a source and a destination DB. When the process has been completed, the source DB will remain unchanged, and the destination DB will contain a compacted copy of the parts of the source which were specified in the copy list.
The transfer of data takes place in two passes, the second of which is further divided into two phases: PASS 1
The data is read from the source DB and written to a pair of intermediate files. The first file holds the element structures and the non-reference attributes, the other holds the reference attributes.
PASS 2 - Phase 1
The first file is read by RECONFIGURER and used to recreate the original structures in the destination DB, including setting of the non-reference attributes.
PASS 2 - Phase 2
The second intermediate file is read and its contents used to set all reference attributes in the destination DB and to perform insertion operations.
The reason for the two phases is that references in the source DB may refer to elements lower down in the hierarchy. It is necessary, therefore, to create all elements in the destination DB before trying to set references to any of them. Since the two passes perform independent and consecutive operations, the process can be interrupted after Pass 1 has been completed, with Pass 2 being run later. Reconfiguration has four basic steps: 1. Specify where the data to be reconfigured is coming FROM 2. Specify where the reconfigured data is going TO. 3. Specify which parts of the source data are to be copied to the destination. 4. Start the reconfiguration process.
3.4.2
Specifying the Source Database The source of the data to be copied is specified using the FROM command. Some examples of the use of FROM are: Examples:
FROM DB STEELS/STEELS Source data is in database STEELS/STEELS in current project
FROM PROJECT XXX STEELS/STEEL Source data is in specified DB in project XXX
FROM DBFILE /abc016 Source data is in specified file (assumes project directory is current directory)
Specifying the Destination DB The destination of reconfigured data is specified using the TO command. Some examples of the use of TO are: Examples:
TO DB STEELS/STEELS Reconfigured data to go to database STEELS/STEELS in current project
TO NEW HVAC/HVAC DBNO 777 Reconfigured data to go to new database USERM/DESIGN, number 777, in current project
TO DBFILE /des008 Reconfigured data to go to specified file (assumes project directory is current directory) TO DB and TO DBFILE specify that the data are to be reconfigured into an existing DB, identified by its name or that of the file containing it. The destination DB must be of the same type as the source DB, and will normally be empty, but need be. For an explanation of what happens when the DB is not empty, see Copying Parts of Databases. TO NEW specifies that a new DB is to be created to receive the reconfigured data. This is the most common option for the general compaction of DBs. It is explained further in Copies and Reconfigured Copies of DBs. Note: The new database will need to be added to the appropriate MDBs.
3.4.4
Specifying What Will be Copied The RCFCOPY command specifies which parts of the source DB are to be copied to the destination. Most commonly a whole DB is reconfigured, using the command option:
RCFCOPY ALL The RCFCOPY ALL command copies all elements in the list part of the World element of the source DB into the World element of the destination DB. World itself is not copied. Parts of a database can be copied by using the RCFCOPY command followed by the name of the element at the top of the hierarchy to be copied. Only elements that can be owned by World, for example, Sites, can be specified. The list of elements specified by the RCFCOPY command becomes the copy list. Note that you must use RCFCOPY ALL if you intend to use the RECONFIGURE SESSIONS command at the next step, as the SESSIONS option is not valid if you only carry out partial reconfiguration.
3.4.5
Starting the Reconfiguration Process The reconfiguration process is started by giving the command:
RECONFIGURE (minimum abbreviation RECON) Messages are output to indicate the successful start and completion of each stage. When the process is complete, all information concerning the source, destination, copy list and the
extent of information output is deleted, ready for another reconfiguration operation if required. You must specify the source, destination and copy list for each reconfiguration. The output by default is sent to the screen, but you can send it to a file by giving the ALPHA FILE command, followed by a filename, before reconfiguration. You can use the following options with RECONFIGURE:
3.4.6
•
Use the SAMEREF option to ensure that the same reference numbers are maintained after reconfiguration. See Using the SAMEREF Option, for details.
•
Use the SESSIONS option to ensure that the session information stays the same after reconfiguration. See Using the SESSIONS Option for details.
Example of a Simple Reconfiguration The following command sequence might be used to reconfigure a DB which is not referenced by any other DBs:
FROM DB MASTER/DESIGN TO DB MASTER/DESNEW RCFCOPY ALL RECONFIGURE Note: In practice it would be advisable to use RCFUPDATE and DUMP in the command sequence. See Updating References into a Reconfigured Database and Saving the Reference Number Index. The following messages are typical of the output during a completely successful reconfiguration:
*** Pass one initiated *** *** Pass one completed *** *** Pass two initiated *** EC SITE #32/202 =42/205 Phase one complete - starting phase two *** Pass two completed *** ***Reconfiguration Completed 0 Elements were not defined in DDL 0 Elements have been lost 0 Elements are no longer named 0 Attributes were incorrectly defined 0 Elements were not inserted. See Reconfiguration Messages, for a complete list of output messages.
3.5
Using the SAMEREF Option When a DB is reconfigured, the reference numbers of the elements in the destination DB will be different from the corresponding reference numbers in the source DB. To ensure that
the same reference numbers are maintained after reconfiguration, you can use the command:
RECONFIGURE SAMEREF In this case the destination DB number must be the same as the original one. This means that you will have to delete the source database, and create a new one with the same number. The following example illustrates the use of the SAMEREF option:
FROM DB MASTER/DESIGN TO FILE /F1 /F2 RCFCOPY ALL RECONFIGURE DELETE DB MASTER/DESIGN CREATE DB MASTER/DESIGN DESI DBNO nn FROM FILE /F1/F2 TO DB MASTER/DESIGN RECONFIG SAMEREF
3.6
Using the SESSIONS Option When a DB is reconfigured, by default the session information from the source DB is not preserved. To ensure that session information such as the original session comment, session number, username and original date stays the same after reconfiguration, you can use the command:
RECONFIGURE SESSIONS The option is not valid for SYSTEM, or GLOBAL DBs, and is not available for a partial reconfiguration. The following example illustrates the use of the SESSIONS option:
FROM DB CTBATEST/DESI TO FILE /A /B RCFCOPY ALL RECONFIG SESSIONS After reconfiguration, data can be read back in from the file using the existing commands, replacing the original DB data. When reading in data, the DB number and extract number must be the same as the originating DB number and extract number. For example:
FROM FILE /A /B TO DB CTBATEST/DESI RECONFIG The SAMEREF option is assumed when reading the data. If errors occur, the data is not saved. If you want the data saved even if errors occur, use the FORCE option. For example:
FROM FILE /A /B TO DB CTBATEST/DESI RECONFIG FORCE
Listing the Reference Number Index When a DB is reconfigured without the SAMEREF option, the reference numbers of the elements in the destination DB will be different from the corresponding reference numbers in the source DB. An index of the reference numbers of elements in the new DB against those in the old DB is automatically created as an essential part of the reconfiguration process. The new reference corresponding to an old reference can be queried using the command:
Q NEWREF refno where refno is the new reference number. The old reference number will be returned. For example:
Q NEWREF #32/202
3.8
=42/205
Global Projects In a Global project, you can reconfigure the System and Global databases. The commands are:
FROM SYSTEM RECONFIGURE (The above command also works in a non-Global project.)
FROM GLOBAL RECONFIGURE In both these cases, the existing System or Global databases will be overwritten, so you do not give a TO command. The COPY ALL and SAMEREF options are also implied. In a Global project, you can only give a RECONFIGURE command for a System or Global database if you are at the primary location of the database:
3.9
•
For a Global database, the primary location is the Hub.
•
For a Satellite System database, the primary location may be at the Satellite itself, or it may be at another Satellite, or at the Hub. The RECONFIGURE command reconfigures the currently open System database. At a Satellite, the command can therefore operate either on the local System database, or on another Satellite’s System database which is primary at the local Satellite.
Controlling RECONFIGURER Output You can control the format and extent of the output produced by RECONFIGURER during Pass 2 processing. The commands are:
VB
Very brief output mode
BRIEF
Brief output mode
FULL
Full output mode
In VB (Very Brief) mode, a message is output as each element in the copy list is successfully created. If the copy command was RCFCOPY ALL, then a message is output for each element successfully copied into the World of the destination DB.
In BRIEF mode, all information output in VB mode is given, plus messages describing any errors that have occurred due to DDL changes. In FULL mode, all information output in BRIEF mode is given, plus a log of all elements successfully created and named. Note that FULL mode is very verbose and its use is not generally recommended. The default is BRIEF mode. An upper limit may be set on the number of errors that are acceptable during Pass 2 of a reconfiguration using the ERRORS command. For example:
ERRORS 50 If the specified limit is reached, reconfiguration is abandoned and the DB is left unaltered. By default, RECONFIGURER allows an unlimited number of errors to occur. This situation may be reset if necessary by using the ERRORS command followed by a negative value. For example:
ERRORS
3.10
-1
Copies and Reconfigured Copies of DBs There are two ways of copying a DB in PDMS, which create two different types of copy: copies and reconfigured copies. This section explains the difference.
3.10.1
Copies A copy of a DB can be made by using the RCFCOPY command. For example the following command: will create a copy of the existing DB PIPEA/PIPEA in the new DB ADMIN/TEST.
RCFCOPY PIPEA/PIPEA ADMIN/TEST The key features of copies are: •
All copies of DBs have the same DB number. This may be seen by using the LIST FILES command. For example: MASTER/DES
3.10.2
DESI
NUMBER 14
FILENAME /%DRA000%/dra013 UPDATE
PIPEA/PIPEA DESI
NUMBER
2
FILENAME /%DRA000%/dra001 UPDATE
ADMIN/TEST
DESI
NUMBER
2
FILENAME /%DRA000%/dra003 UPDATE
USER/DRAFT
PADD
NUMBER
5
FILENAME /%DRA000%/dra004 UPDATE
•
There is no implied direction of copying. Thus, in the previous example, PIPEA/PIPEA and ADMIN/TEST are each a copy of the other.
•
The contents of all copies are identical with respect to both data and structure.
•
Any given element has the same reference number in each copy.
•
A DB may have any number of copies, but copies may not exist in the same MDB.
Reconfigured Copies A reconfigured copy is one named by the TO DB or TO NEW commands. The key features of reconfigured copies are: •
A reconfigured copy has a different DB number from that of the source DB.
In the reconfiguration process, the destination DB becomes a reconfigured copy of the source DB, but the reverse is not true. The relationship exists in one direction only.
•
The contents of a reconfigured copy are an edited version of those of the source DB.
•
Any given element will have a different reference number in the reconfigured copy from its reference number in the original DB (unless you use the same SAMEREF option).
Advanced Reconfiguration The previous sections in this chapter describe how a single DB can be reconfigured. In a real PDMS project, with many DBs of different types and with reference attributes pointing from one DB to several other DBs, reconfiguration is usually a more complex process. This section describes how one or more DBs can be reconfigured in such an environment. It also describes how part of a DB can be reconfigured, rather than the whole DB. Note: If the SAMEREF option is used, the reconfiguration is much simpler
3.11.1
References Between Databases A DB often contains elements which have reference or reference array attributes which point into other DBs. For example, one Design DB could contain a Branch connected to a Nozzle in another Design DB. The HREF (or TREF) attribute of the Branch would point into the second DB and the CREF attribute of the Nozzle would point back into the first DB. See example below:
HREF /E1-N2
Branch /150-B1
DESIGN DB 1 CREF /150-B1 Nozz /E1-N2 DESIGN DB 2
Similarly, references can exist from Design DBs into Catalogue DBs (the SPREF attribute of a piping component pointing to an SPCOM, for example), but references cannot exist from a Catalogue DB back into a Design DB. When a DB is reconfigured without the SAMEREF option, most of the reference numbers of its elements will change. To maintain the integrity of pointers into the DB from other DBs, the contents of any DB which might point to elements in the reconfigured DB are scanned and the reference or reference array attributes are changed to point to the correct element once more. For example, assume that the reference number of an SPCOM in a Catalogue DB changes from =17/3108 in the original DB to =49/2014 in the reconfigured copy. All piping components whose SPREF attribute was previously set to =17/3108 must have SPREF reset to =49/2014. Such components might exist in several DBs. Reference resetting is performed by the RCFUPDATE command described in the next section.
Updating References into a Reconfigured Database While a DB is being reconfigured without the SAMEREF option, RECONFIGURER builds up an index of the reference numbers of all elements in the source DB versus their corresponding new reference numbers in the destination DB. The RCFUPDATE command uses this index to check reference pointers in other DBs and update them to point to the correct elements in the reconfigured DB. Examples of the use of this command are: Examples:
RCFUPDATE DB MASTER/DESIGN Updates references to the reconfigured DB from DB MASTER/DESIGN.
RCFUPDATE DB MASTER/DESIGN INTERNAL Updates references in DB MASTER/DESIGN for any elements that have been copied with RCFCOPY ALL CONNECTIONS. Use this option with care because it is possible to update a reference that has already been changed by the RECONFIGURE command.
RCFUPDATE MDB /USERA Updates all references to the reconfigured DB from DBs in MDB /USERA.
RCFUPDATE TEAM USER Updates all references to the reconfigured DB from DBs owned by team USER. Note: The RCFUPDATE command must be given immediately following a RECONFIGURE operation. As the RCFUPDATE command may cause a DB to be written to, you must have Read-Write access to all relevant DBs. The DBs must not be in active use by any other user of the project. Care should be taken when reconfiguring to the same DB number. If you update a DB twice, the resulting reference numbers could be wrong. For example: Old reference
New reference
/VESS1
=123/456
=123/457
/VESS2
=123/457
=123/458
Thus, giving the RCFUPDATE command twice results in the reference =123/456 being reset to =123/458.
RECONFIGURER knows which types of DB can be pointed to by reference attributes in other types of DB, and so does not attempt to update DBs which could not possibly point to the latest reconfigured copy. A report is output which lists which DBs were and which were not updated. The table of references is maintained across multiple reconfigurations, as long as you do not exit from ADMIN.
Saving the Reference Number Index The RCFUPDATE command is usually given immediately after databases have been reconfigured. The index can be saved to a file when the reconfiguration has been completed; to be used at a later date. The commands are DUMP to save to a file, and LOAD to load a file. For example:
LOAD /DUMP1 FROM DB MASTER/DESIGN TO DB MASTER/DESNEW RCFCOPY ALL RECONFIGURE DUMP /DUMP2 These commands will read an existing reference number index from file /DUMP1, add the reference number pairs from the specified reconfiguration to it, and then write the index out again to the file /DUMP2. If a number of databases have been reconfigured, the dump file will record the crossreference index for all of them. The LOAD command replaces the current index. The command LOAD APPEND appends the table to the current index.
3.11.4
Copying Parts of Databases The RCFCOPY ALL command copies all the elements in the source DB World into the destination DB World. If the World of the destination DB already contains members, then the elements from the source DB are added to these. The RCFCOPY command can be used to define the root elements to be copied. A root element is any element owned by the World, that is:
BLTA
CASW
CATA
CCTA
CMPW
CONW
DEPT
GPWL
LIBY
MATW
RUNW
SITE
SPWL
UNIT
UWRL
When a root element is copied, all elements owned by it are also copied. A maximum of 300 root elements may be specified in a single copy list. The selective commands RCFCOPY CATALOGUE and RCFCOPY SPECIFICATIONS cause the first root elements of type CATA and SPWL, respectively, to be copied from the list part of the World in the source DB. To copy only part of a DB, one or more root elements must be specified (by name or reference number) in a RCFCOPY command. For example:
RCFCOPY /SITE-A SITE-7 Elements of any other types will be copied into the destination DB as NULL elements, that is they will be created as floating elements, not owned by any higher-level element. This does not mean that they are inaccessible. As long as such an element is named (or you know its new reference number) it can be incorporated as a member of any suitable parent element by using the INCLUDE command.
If you are not at a top level element, there must be an existing element in the destination DB into whose list part you wish to incorporate the element being copied. This is done using the INTO option of the RCFCOPY command. For example:
RCFCOPY /ZONE5A INTO /SITE-3 would copy the Zone /ZONE5A and make it the last member of the Site /SITE-3. If the intended owning element does not already exist in the destination DB at the beginning of Pass 2, the listed root element will not be copied. For example:
RCFCOPY /SITE-3 /ZONE5A INTO /SITE-3 is not allowed. INTO cannot be used when the destination is FILES rather then a DB. The word AND and the comma (,) may be used as separators to improve readability, thus: RCFCOPY /SITE-5, /ZONE5A INTO /SITE-3, /SITE-6 AND /SITE-12
Several RCFCOPY commands can be given in sequence to add elements to the copy list. For example, the sequence
RCFCOPY /SITE-5 RCFCOPY /ZONE5A INTO /SITE-3 RCFCOPY /SITE-6, /SITE-12 is exactly equivalent to the RCFCOPY command in the previous example. If an element is quoted in the copy list but does not exist in the source DB, an error message is output and the element is not copied. Since RCFCOPY commands are additive, a correcting command may be given on the next line. For example:
RCFCOPY /SITE1 /SITE2 /SITR3 /SITE4 (24,16) SITR3 not found
(error message)
Since SITE1, SITE2 and SITE4 are already in the copy list, all that is needed to add SITE3 is:
RCFCOPY /SITE3 Note: Partial reconfiguration of PADD DBs is only allowed for picture elements (i.e. SHEE, BACK, OVER, SYLB, LALB) and above. Setting External References In cases where you have made a partial copy of a database, sometimes it is necessary for you to ensure the external references are correct in the copied elements. For example, if you moved a piping zone to a different database while maintaining the references to an equipment zone which was to remain it the original database, the copied piping zone could have unset external references and the equipment zone would remain connected to the original piping zone. In these cases you can use the ALLCONnections option to set the external references for the reconfigured elements:
RCFCOPY /SITE1 INTO /SITE2 ALLCONNECTIONS This will set all references including those within the original database not in the list of copied elements.
To update the references of the original database to point to the new copied elements use the RCFUPDATE INTERNAL command described in Updating References into a Reconfigured Database.
3.11.5
Copying Groups If a Group World is specified in a RCFCOPY command, only the Group World and its owned Groups are copied. Errors will occur in Phase 2 if the Group members have not be copied as well. It is meaningless to try to reconfigure a group on its own.
3.12
Transferring Data Between Projects RECONFIGURER provides a simple means of transferring data from one project to another, on the same type of computer, provided both projects are running under the same major version of PDMS and provided cross-referencing between DBs is considered logically. The transfer operation in this case requires the use of the FROM FILES and TO FILES options of the FROM and TO commands. In the simplest case, namely the transfer of the contents of a single DB, such as a Catalogue, the following sequence of commands could be used: In the source project: Example:
FROM DB /CATOLD Specify source DB.
TO FILES /TEMP1 /TEMP2 Only pass 1 of reconfiguration to be carried out; partially reconfigured data to be stored in named files.
RCFCOPY ALL RECONFIGURE and in the destination project: Example:
FROM FILES /TEMP1 /TEMP2 Partially reconfigured data to be recovered from named file;
TO DB /CATNEW pass 2 of reconfiguration to be done.
Note: FREE (i.e. Read/Write) access is required to both projects. If the contents of more than one DB are to be transferred, provided no reference attributes point outside the set of DBs being transferred, an extension of the same procedure could be used. Consider the transfer of the whole of one Design DB, the whole of a Catalogue DB and one item of equipment from a second Design DB, thus: Source DB
Elements Transferred
Destination DB
CIVIL/STRUC4
Whole Design DB
STEEL/MAIN
ANSI/MASCAT
Whole Catalogue DB
CATAL/MAIN
SITE-A
One Site
EQUIP/MAIN
The reconfiguration commands should be given in the following order: In the source project:
FROM DB ANSI/MASCAT TO FILES /REC1A /REC1B RCFCOPY ALL RECONFIGURE
Copies the Catalogue DB first
FROM DB CIVIL/STRUC4 TO FILES /REC2A /REC2B RCFCOPY ALL RECONFIGURE
Copies the Design DB
FROM DB VESSEL/V25CT TO FILES /REC3A /REC3B RCFCOPY /SITE-A RECONFIGURE
Copies the Site
and in the destination project:
FROM FILES /REC1A /REC1B TO DB CATAL/MAIN RECONFIGURE
Creates Catalogue DB
FROM FILES /REC2A /REC2B TO DB STEEL/MAIN RECONFIGURE
Creates Design DB
FROM FILES /REC3A /REC3B TO DB EQUIP/MAIN RECONFIGURE
Creates equipment item
RCFUPDATE DB STEEL/MAIN RCFUPDATE DB EQUIP/MAIN
3.13
Gives correct cross-references
Upgrading a Project The XREF and RESETXREFS commands described in this section are intended for use during the upgrading of a project from one version of PDMS to the next. They operate on the
data during its transfer from the source DB to the destination DB such that the data can be modified to conform to the requirements of a new DDL. The commands are used to ensure that all cross-references are correctly set after a multiDB reconfiguration. They are particularly useful in the case where two databases of the same type are referencing each other. They are also useful when copying between projects, as an alternative to the UPDATE command. When copying between DBs with the same DB number, it is best to use XREF and RESETXREFS. These commands are normally handled automatically by the upgrade macros supplied with a new version of PDMS. They may be used independently of the upgrade macros by the experienced user, preferably after consultation with AVEVA Solutions Limited, and it is for this reason that they are described here. XREF may be used to generate a list of the reference numbers of all elements which need updating for each DB. The list is created during the restructuring of the new DBs in Phase 2 of Pass 2. This list is then used to monitor a partial updating operation, which ensures that all references are reset into every element which has been affected by a DB reconfiguration. The partial update is controlled by the RESETXREFS command, which is related to the RCFUPDATE DB command. The RESETXREFS function applies only to elements whose reference numbers appear in the corresponding XREF file. For example:
RESETXREFS WITH /REFFILE RESOLVE DB MASTER/DESNEW RESET /REF2 RESOL /NEWDB Here /REFFILE is the name of the file generated by the XREF command and MASTER/ DESNEW is the corresponding DB to be updated. In effect the RESETXREFS command opens the specified XREF file and the RESOLVE command part initiates the appropriate update. The macro files generated by the UPGRADE command in ADMIN ensure that the RESET filenames are correctly matched to the corresponding RESOLVE dbnames. Note: The XREF file only indicates those elements which need to be updated. The DUMP files are still required in order to match the old and new reference numbers correctly. When reconfiguring a whole project, it is impossible to order databases of the same type so that all references are resolved as the reconfiguration proceeds. The XREF and RESETXREFS commands are needed to tidy up the references. Note: The UPGRADE command is used when a project is being upgraded from an earlier version of PDMS.
The following is an example of a sequence of commands: Example:
TO DB XX/A2 FROM DB XX/A1 XREF /XX1 RCFCOPY ALL RECONFIG : : TO DB XX/B2 FROM DB XX/B2 RCFCOPY ALL RECONFIG RESET WITH /XX1 RESOLVE DB XX/A2 A more general command sequence for a project upgrade is shown in the following input and output macros: Input macro Write ’Upgrading project CJB ’ Write ’From PDMS10 to PDMS11 ’ Write ’Input phase ’ $R6 Checkddl is 11 To db STANA/SAPROP From files /REC1A /REC1B Xref /REC1X Reconfigure To db DEREKF/DFPROP From files /REC2A /REC2B Xref /REC2X Reconfigure To db ALANC/ACPROP From files /REC3A /REC3B Xref /REC3X Reconfigure To db TAMH/THPROP From files /REC4A /REC4B Xref /REC4X Reconfigure To db TAMH/PROP_ATEST From files /REC5A /REC5B Xref /REC5X Reconfigure Reset with /REC1X Resolve db STANA/SAPROP Reset with /REC2X Resolve db DEREKF/DFPROP Reset with /REC3X Resolve db ALANC/ACPROP Reset with /REC4X Resolve db TAMH/THPROP Reset with /REC5X Resolve db TAMH/PROP_ATEST Finish
Output macro Write ’Upgrading project CJB ’ Write ’From PDMS10 to PDMS11 ’ Write ’Output phase ’ $R6 UPGRADE ON From db STANA/SAPROP To files /REC1A /REC1B Copy all Reconfigure From db DEREKF/DFPROP To files /REC2A /REC2B Copy all Reconfigure From db ALANC/ACPROP To files /REC3A /REC3B Copy all Reconfigure From db TAMH/THPROP To files /REC4A /REC4B Copy all Reconfigure From db TAMH/PROP_ATEST To files /REC5A /REC5B Copy all Reconfigure
3.14
Reconfiguration Messages During the various stages of the reconfiguration process, messages will be output. This is particularly so during Pass 2, in which the data from the intermediate files is used to reconstruct the element hierarchy in the destination DB. In the simplest case these messages will just indicate the start and finish of each phase, and confirm that all elements and their attributes were correctly placed. In a more complex case it is probable that a number of error messages will also be output, indicating potential problems in building up an unambiguous structure in the new DB.
3.14.1
Standard Information Messages The progress-monitoring messages, which indicate the stages reached during the reconfiguration, are self-explanatory. They are:
*** Pass one initiated *** *** Pass one completed *** *** Pass two initiated *** : *** Pass two completed *** ***Reconfiguration Completed After the reconfiguration has been completed, a summary of any problems found during Pass 2. This will contain zero values where no problems were found.
General Format of Pass 2 Error Messages In addition to the standard information messages described above, a range of error messages may be generated during Pass 2. These messages have the general format: CODE TYPE OLDREF NEWREF NAME although some parts of this may be omitted. For example:
EN EQUIP #10/21 =12/12 /NEWNAME #EAE SHEE #88/842 =16/2417 /DR1/S5 *ENID SITE #15/23 The individual parts of the message are:
3.14.3
CODE:
Identifies the nature of a message arising from the creation or naming of an element. The codes used are detailed in the next section.
TYPE:
The type of element, e.g. SITE, BRAN, SHEE etc.
OLDREF
The reference number of the element in the source DB (starting with ‘#’).
NEWREF:
The reference number of the corresponding element created in the destination DB (starting with ‘=’). This will be blank if the element could not be created.
NAME:
The name given to the element. This applies only if the message is coded ‘EN’ to indicate that the element has been named (see next section).
Codes Used to Identify Message Types The coded prefix to each message comprises two parts. The first character is one of the following: •
A space indicates information rather than an error
•
An asterisk (*) indicates an error concerning the creation or naming of an element
•
A hash (#) indicates an error concerned with an attribute
The remaining characters, which give more explicit meaning to the message, are explained in the following subsections.
Information-only Messages (prefix: space) There are two possible codes:
EC
Element Created
EN
Element Named
These are output as the reconfiguration proceeds and each message ends with the name of the copied element. Error Messages Relating to Elements (prefix: asterisk)
*ENID
Elements Not In DDL
The element could not, therefore, be created. This can occur when the element type is not permitted in the list part of the element above it in the DB hierarchy, for example, if an attempt is made to reconfigure FROM FILES into a DB of the wrong type.
*ENI
Element Not Inserted
An attempt was made to insert the element into a list where it is no longer permitted.
*EL
Element Lost
Elements in the list part of ones that cannot be created are lost, since they cannot be created either. Error Messages Relating to Attributes (prefix: hash sign) These all begin with
#EAE
Element Attribute Error
followed by one or more other messages giving more information about the error.
3.15
Database Transfers between Computers Note: The hardware platforms currently supported allow binary compatibility of databases, and so the information in this section will not usually be needed. RECONFIGURER can be used for the transfer of PDMS DBs between different computers, which may be of different types. Because reconfiguration is a two-pass operation, the data can be copied from one computer and read back into a different one. The transfer operation is essentially an extension of the procedure for copying data between projects, described in Transferring Data Between Projects. RECONFIGURER makes provision for translating the coding of the intermediate files to ensure compatibility between the language requirements of different computers. An alternative method of transferring data between different computers is to use the OUTPUT command in DESIGN, DRAFT, PARAGON or LEXICON. For details of other data transfer methods, see the DESIGN Reference Manual Part 1 (OUTPUT command).
Binary and Character Files Data can be stored in two formats: •
Binary files are in a compact machine-readable form, but are generally specific to a particular type of computer.
•
Character files (which are usually in ASCII code) generally have to be much larger to hold the same amount of information, but are human-readable. Character files can be transferred relatively easily between different types of computers.
PDMS DBs are stored as binary files so that large amounts of data can be held efficiently. RECONFIGURER provides a means to convert PDMS DBs from binary files into character files and vice versa.
3.17
Transfer Process The files used by the transfer process are not the PDMS DBs themselves but the (binary) intermediate files created by Pass 1 of a reconfiguration. These are converted into larger, but easily transportable, character files by the TO FORMATTEDFILES command. The files can then be transferred to the target machine via a communications network or magnetic tape and converted back into Pass 1 temporary file format by the FROM FORMATTEDFILES command. For example: On source machine:
FROM DB MASTER/DESI TO FORM /F1 /F2 RCFCOPY ALL RECONFIG On destination machine:
FROM FORM /F1 /F2 TO DB MASTER/DESI RECONFIG
3.18
Reconfiguring a Global Project We recommend that you use the SAMEREF option when reconfiguring a Global project. We also recommend that there are no users in the database at the primary location when reconfiguring back to the SAMEREF database. Databases can only be reconfigured at their primary locations. Note that when a project database is reconfigured, the database sessions will effectively be lost. Thus the ability for Global to send only session changes is lost as well. When the next update occurs between locations, the entire database will be sent via the Global daemon. This can take some time if the database is large.
Outputting Changes Only The default for reconfiguration is that, when reconfiguring an extract, only changes made in the extract are output. To output all elements, as in normal reconfiguration, the keyword FULL must be added to the RECONFIGURE command line. For example:
RECONFIG FULL
3.19.2
The SAMEREF Option The SAMEREF option is always used for extracts. You need not to enter the SAMEREF option; it is assumed. This means that you can not reconfigure to DBs of a different DB number.
3.19.3
The SESSIONS Option The SESSIONS option is always used for extracts. You need not enter the SESSIONS option; it is assumed.
3.19.4
Reconfiguring a Single Extract The procedure for reconfiguring a single leaf extract is as follows: 1. Reconfigure from the DB to a file. 2. REVERT the extract to Session 1. 3. MERGE CHANGES to remove the intermediate session. 4. Reconfigure from the file to a DB. An alternative strategy would be to replace Steps 2 and 3 by a DB deletion and a DB creation. The procedure is similar for single extracts that own other extracts. The only difference is:
3.19.5
•
The MERGE CHANGES command will leave sessions referred to by child extracts. Thus, the resultant file will be larger than it would have been had there been no extract children.
•
The alternative approach of deleting and recreating the extract is not possible unless all child extracts are also deleted and recreated.
•
The Master DB should be reverted to Session 2 rather than Session 1.
Reconfiguring a Family of Extracts When reconfiguring a whole extract family, the following considerations apply: •
The REVERT/MERGE operation must be done bottom-up, to minimise the number of sessions kept.
•
Reconfiguring from databases to files must be done top-down.
•
Reconfiguring back from files to databases must also be done top-down, and you must complete the reconfiguration for the whole extract. For example, if you reconfigure all three database levels of a three level extract to files but only reconfigure the top two file levels back to databases, the third database will be corrupted due to the reconfiguration of the other two. Refer to Example of Reconfiguring a Three Level Extract for more information.
Before reconfiguring out from a file, refresh the extract.
•
Before reconfiguring in from a file, the extract must be refreshed from its parent.
For example, given a simple two-level extract containing TEAMA/MASTER, TEAMA/ EXTRACT, the sequence would be: 1. Refresh TEAMA/EXTRACT. 2. Reconfigure TEAMA/MASTER to file /A, /B. 3. Reconfigure TEAMA/EXTRACT to file /C, /D. 4. REVERT TEAMA/EXTRACT to Session 1. 5. MERGE CHANGES on TEAMA/EXTRACT. 6. REVERT TEAMA/MASTER to Session 2. 7. MERGE CHANGES on TEAMA/MASTER. 8. Reconfigure from file /A, /B to TEAMA/MASTER. 9. Refresh TEAMA/EXTRACT (to pick up changes made in Step 8). 10. Reconfigure from file /C, /D to TEAMA/EXTRACT.
3.19.6
The RCFUPDATE Command When the RCFUPDATE command is used on an extract, all affected attributes will be updated regardless of whether or not the element has been claimed to the extract. This means that, if many extracts of the same extract family are updated, the same changes will be made to each of the extracts.
3.19.7
Example of Reconfiguring a Three Level Extract Consider this three-level extract:
All databases must be reconfigured to files first and then reconfigured from the files to the databases, in the order; MASTER, EXT, EXTBOT. If this sequence of operations is not completed, then databases will be corrupted. For example, if EXTBOT is not reconfigured from file, then EXTBOT will be corrupted as a result of the reconfiguration of the other two databases. It is therefore suggested that you make backups of databases before reconfiguring them. The sequence of commands to reconfigure the above three level extract could therefore be: Note: The REFRESH, REVERT and MERGE CHANGES commands have not been shown below.
FROM DB CTBATEST/MASTER TO FILE /MASTERA /MASTERB RCFCOPY ALL RECONFIG SESSIONS
FROM DB CTBATEST/EXT TO FILE /EXTA /EXTB RCFCOPY ALL RECONFIG SESSIONS FROM DB CTBATEST/EXTBOT TO FILE /EXTBOTA /EXTBOTB RCFCOPY ALL RECONFIG SESSIONS FROM FILE MASTERA /MASTERB TO DB CTBATEST/MASTER RECONFIG FROM FILE EXTA /EXTB TO DB CTBATEST/EXT RECONFIG FROM FILE EXTBOTA /EXTBOTB TO DB CTBATEST/EXTBOT RECONFIG It is not necessary for the reconfiguration back from file to be done within the same session of RECONFIGURER. For example, in a global project where MASTER, EXT and EXTBOT are primary at different locations, then the following sequence could be followed: 1. At location A (primary location for MASTER):
FROM DB CTBATEST/MASTER TO FILE /MASTERA /MASTERB RCFCOPY ALL RECONFIG SESSIONS 2. At location B (primary location for EXT):
FROM DB CTBATEST/EXT TO FILE /EXTA /EXTB RCFCOPY ALL RECONFIG SESSIONS 3. At location C (primary location for EXTBOT):
FROM DB CTBATEST/EXTBOT TO FILE /EXTBOTA /EXTBOTB RCFCOPY ALL RECONFIG SESSIONS Steps 1 to 3, reconfiguring from databases to files, can be done in parallel. 4. At location A (primary location for MASTER):
FROM FILE /MASTERA /MASTERB TO DB CTBATEST/MASTER RECONFIG
The user must now propagate the whole database to locations (B) and (C). 5. At location B (primary location for EXT)
FROM FILE /EXTA /EXTB TO DB CTBATEST/EXT RECONFIG The user must now propagate the whole database to locations (C) and (A). 6. At location C (primary location for EXTBOT)
FROM FILE /EXTBOTA /EXTBOTB TO DB CTBATEST/EXTBOT RECONFIG The whole database will be propagated to locations (A) and (B) automatically. Steps 4 to 6, reconfiguring from files to databases, should be done consecutively.
3.19.8
Reconfiguring the Transaction Database in a Global Project The Global Daemon stores most of the commands that it is asked to perform at a location in a transaction database. Each location has its own transaction database. For details, see Transaction Database. If a transaction database becomes corrupt, it may be necessary to reconfigure it. For information about this, refer to Running Global Projects. Note: The daemon for a location must be stopped before reconfiguring its transaction database.
Administrator Command Reference Manual System and Global Projects
4
System and Global Projects This chapter describes how ADMIN elements and their attributes, in a System database differ when a Global project is used. You can navigate to the elements in the System and Global databases, and query their members and attributes in the normal way. A full list of Elements and their Attributes is included in the Data Model Reference Manual. Session information is stored separately in the COMMs database; and the MISC database stores inter-db macros and messages. The communications world element in the COMMs database contains the project lock. This may be set or cleared using LOCK and UNLOCK syntax. When you use the MAKE GLOBAL command to make a standard project into a global project, the Standard System database is split into two new database files; the Global database and the (local) System database. A modified sysvir.dat virgin database is used to upgrade the System database file xxxsys, where xxx is the 3-character project code. The communications world element LCOMW is added. The glbvir.dat database template file is used to create the Global database file xxxglb. The existence of the xxxglb database file shows that the project is global. The following elements are added: •
The communications world element LCOMW
•
The Global Locations world element GLOCW, which will own GRPLI elements which in turn own GRP elements
•
The Global Team World element GTMWL
•
The Global Stamp World element GSTWLD. If stamps exist in the System database, they are all copied to the Global Stamp World element and deleted from the System database.
The attributes of these elements and their members, and the changes to other ADMIN database elements which occur when a Project is made Global, are described in the following pages. The Global database contains information that is common to all Locations running a Global project. The Global database is readable at all locations but is it can only be written to at the Hub. Changes to the Global database are propagated to all the other Locations. This means that the Global database is the same at every Location, except during the short time changes are being propagated. Each local System Database contains project information that is specific to the Location. The local administrator can write to the local system Database. A local System database is
Administrator Command Reference Manual System and Global Projects
similar to the System database in a non-global Project. The main difference is that some of the standard ADMIN elements will be redundant. The differences are described below. Session information is stored separately in the COMMs database; and the MISC database stores inter-db macros and messages. The Comms and Misc databases are local to each Location. The communications world element in the COMMs database contains the project lock and isolation flags. The project lock may be set or cleared using LOCK and UNLOCK; and the Isolation flag may be set true or false using ISOLATION syntax. Both lock and isolation may be set or queried remotely by the Hub or an administering location.
4.1
Structure of the Local System Database
The Local System database contains the data for local Fonts, Modules, Users, MDBs, DB Sets, Scopes and ACRs: these elements correspond to those that existed in the System database of a Standard project. The communications data is held in a new LCOMW Location Communications world element. The Team World and Role Worlds still exist in the local System database, but they are empty. The Team data is stored in the Global Team World element GTMWL in the Global database, and the Role data is stored in the Global Role World. The TEAM and USER elements in the Standard System database cross-reference each other, that is each team element holds a list USLI of users belonging to the team and each user element holds a list TMLI of teams to which the user belongs. In the Global database, a Team does not maintain a USLI list of users belonging to it.
Administrator Command Reference Manual System and Global Projects
Note: This means that a report of all Users at every Location in the Project can only be obtained by combining reports from each Location. The TMLI list in the USER element in the Local System database will continue to provide a list of teams to which a user at a particular location belongs. In the same way that a TEAM element no longer maintains a list of users in that team, a DB element in a team does not maintain a list of MDBs to which the DB belongs. The MDB element, in the Local System database keeps a list of DBs belonging to it. The detailed changes to the elements and attributes are described below.
STAT Element This element already exists in the Local System database, but certain attributes have been relocated to the Global System database. The attributes are the same as in a Standard Project with the addition of: Locrf
text(120)
120 character text: current Location Reference
Note: When a location is created, the LOCRF attribute in its local system DB will be set to the reference of its LOC location element in the global system database.
LCOMW Element The Location Communications World element LCOMW is called /*LC. It contains elements that describe the communications between one Location and all the other Locations with which it can communicate. The LCOMW element owns a LCOMC element, LCOML elements and LCTIML elements.
LCOMC Element The LCOMC element contains general details about the configuration of the Admin daemon at the current location. There should be only one LCOMC element in the database. Attributes: Name
/name
Lock
false
Owner
/*LC
Logfn
/filenam
Logms
false
Loglv
0
Log file name
Diagnostic level
LCOML Element The LCOML element contains a list of LCOMD elements, each of which specifies details about the communications link between the current site and one other site, as described below.
Administrator Command Reference Manual System and Global Projects
Attributes: Name
/name
Type
LCOML
Lock
false
Owner
/*LC
LCOMD Element The LCOMD element contains specific details about the communications link between the current site and one other site, and controls scheduled updates. There will be one LCOMD element for each location, which has a communications link with the current location. Attributes: Name
/name
Lock
false
Owner
/name
Description
unset
120 character text
Locrf
/name
Name of Location which has comms link with current Location
Timer
frequency of update events 120 character text: (See below)
Times
0
Time window start
Timee
2400
Time window end
Timei
30
Interval in seconds between communication attempts
Timeo
10
Number of re-tries
Execb
unset
120 character text: name of script to be run before updates are transferred (optional)
Execa
unset
120 character text: name of script to be run after updates are transferred (optional)
LNoUpd
false
If set TRUE, the scheduled update is disabled. This is useful during certain house-keeping operations such as merging.
Administrator Command Reference Manual System and Global Projects
Months
1 - 12
Days of the week
0 (Sunday) - 6
For example: Timer '0,30 * * * *'
specifies every half hour, every day.
Timer '12 10,12,14,16,18 * * 1,5 '
specifies 12 minutes past the hours given, Monday to Friday.
The attributes TIMES and TIMEE are not implemented at this release. Files such as Isodraft external plot files are not propagated automatically by the global daemon. However, there is a mechanism in the daemon to allow such files to be transferred to and from neighbouring locations, during scheduled updates (or the UPDATE ALL command). The directory to receive transferred files is defined by the environment variable %IMPORT%. Each location to which files are to be transferred requires its own transfer directory - %EXP_ABC% for location ABC. Transfer of other data is described more fully in the Global User Guide. Offline locations: Note that transfer of such files to or from offline locations must be done manually.
LCTIML Element The LCTIML element is present in a Global project only and has the following functions: •
It overrides the default transaction event timings.
•
It contains a LEVENL attribute, which sets the time interval for the event loop for all locations, in seconds.
•
It contains attributes that control the frequency of automatic merges on the transaction database.
•
It contains a list of LCTIMD elements, each of which specifies details about the event timings between the current site and one other site, as described below.
Attributes: Levenl
5
Time interval for event loop (secs)
Lmerti
Frequency of Automerges. 120 character text:
(settings as for Timer above) Lmersu
3
Time in days after which successful commands should be deleted. The value -1 means no deletion.
Lmerfa
3
Time in days after which failed commands should be deleted. The value -1 means no deletion.
Lmerdl
false
If true, transaction database is merged and purged at specified times.
At times specified by LMERTI, the transaction database will automatically be merged and commands deleted as specified by the LMERSU and LMERFA attributes. The LMERDL attribute must be set to true. For example, the automerge data could be set as follows:
Administrator Command Reference Manual System and Global Projects
•
LMerti ’59 23 * * 3,6’
•
LMersu 10
•
Lmerfa -1
•
Lmerdl true
In this example, the daemon would delete all successful commands older than 10 days and merge the transaction database. Failed commands would not be deleted. Note: If both LMERSU and LMERFA are set to -1, then the transaction database will not be merged.
LCTIMD Element The LCTIMD element contains details about the event timings between the current site and one other site. There will be one LCTIMD element for each location that communicates with the current location. Attributes
4.2
Name
/name
Description
unset
120 character text
Locrf
/name
Reference to Location communicating with current Location
Lendti
604800
Command timeout period, in seconds (default is 7 days in seconds)
Lmaxtr
100
Maximum number of retries to send command
Ltimei
120
Time interval between retries, in seconds
Structure of the Global Database The Global System database contains Teams, Databases, Roles, Locations and Stamps. Figure 4:1.: Structure of the Global System Database shows the structure of the Global System database.
Administrator Command Reference Manual System and Global Projects
WORLD World
/*GS GSTAT Global Status World
GRPLI Group List
GRP Groups
/*GL GLOCWL Location World
LOCLI Location List
/*GT GTMWL Global Team World
/*GST GSTWLD Global Stamp World
ROLE Roles
TEAM Teams
STAMP Stamps
PEROP Perops
DBLI DB List
STLST Stamp List
/*GRO GROLW Global Role World
LNKLI Links List
LOC Locations
LNK Links
DB DBs
DBLOC
Figure 4:1.
Structure of the Global System Database
GSTAT Element (GSTAT) Only one /*GS element can exist in the database and it is inherited from the STAT element in the Standard System Database. Attributes Name
Administrator Command Reference Manual System and Global Projects
GTMWL Element The Global Team World element GTMWL is named /*GT. Only one /*GT element can exist in the database. It is the same as the TMWL element, except that: •
It does not own a user list element USLI.
•
The DB element does not own an MDB list element MDBL.
•
The DB element owns a single DBLOC element DBLOC.
Attributes Name
/*GT
Lock
false
Owner
/*
TEAM Element Attributes Name
/name
Lock
false
Owner
/*GT
Description
unset
Database List Element (DBLI) Attributes Name
/name
Type
DBLI
Lock
false
Owner
/name
DB Element The DB element owns the list element DBLOC which holds four additional attributes (see DBLOC Element). These attributes are attached to the DBLOC element to facilitate separate claiming of both this element and the owning DB element. This scheme reduces the contention between the PDMS ADMIN module and the Global daemon. Attributes Name
Administrator Command Reference Manual System and Global Projects
Opoutput
ignore
Opexport
ignore
Opcopyfrom
ignore
Eclass
unset
Element Class
Aclass
unset
Attribute Class
Condition
unset
Acrmessage
unset
GLOCWL Element The Global Location World element GLOCWL specifies information about Locations, Groups and Communications (Links). It is named /*GL and only one /*GL element can exist in the database. The GLOCWL element consists of the three list elements GRPLI for groups, LOCLI for locations and LNKLI for links. It has the following attributes: Attributes Name
/*GL
Lock
false
Owner
/*
Aduuid
text
Daemon version string (Project UUID)
Hubrf
/name
Hub Location Reference
Prvrf
Nulref
Previous Hub Reference (normally unset)
NxtHb
Nulref
Next Hub location (normally unset)
Newuid
text
gets new UUID value to use when setting ADUUID. To be used when a Global project is copied directly without the REPLICATE command (see REPLICATE (Project definition)) having been used.
GLINKP
false
To enable Link Propagation, the GLINKP attribute must be set to TRUE.
GRPLI Element The GRPLI element contains a list of Group elements GRP. A Group is a fully connected local network of Locations which conceptually form a single node in the Plant Design Global-tree structure of Locations. Attributes Name
Administrator Command Reference Manual System and Global Projects
Lock
false
Owner
/*GL
GRP Element The characteristics of each group are defined by a GRP element which has the following attributes: Attributes Name
/name
Lock
false
Owner
/name
Description
unset
Membership of a group is indicated by the attribute GRPRF in each location element LOC, as described below. The location elements LOC are themselves listed in the LOCLI element.LOCLI Element The LOCLI element contains a list of all Location elements LOC, including offline Locations and those which belong to Groups. Attributes Name
/name
Lock
false
Owner
/*GL
LOC Element The characteristics of each Location are defined by a LOC element which has a set of attributes and a secondary list element DBALL. The DBALL element is a complete list of all Databases allocated to the Location. It is implemented as a Dabacon secondary list of DB reference numbers which refer to DB elements under the DBLI list element of TEAM elements. Locations which belong to a Group have an attribute GRPRF holding the reference number of the Group. If this attribute is null then the Location does not belong to a group. LOC elements also possess a LOCRF attribute which points to the parent of the Location. This attribute is used to determine paths between Locations in the proposed tree structure for connecting Locations. In a future implementation, based on a more general graph structure, the LOCRF attribute might either be dropped or used for another purpose. A Location is only recognised as fully initialised when the logical attribute LINIT is true. Other attributes of a Location are described in the following table. The LOC element has the following attributes:
Administrator Command Reference Manual System and Global Projects
Attributes Name
/name
Lock
false
Owner
/name
Description
unset
120 character text
Locid
XXX
3-letter identifier
Rhost
rhost name
host name
Iconn
1
Connection type: 1 = on-line 0 = off-line
Linit
false
Initialisation flag
Grprf
Nulref
Group reference set if Location is added to a Group
Locrf
/name
Parent Location
PRMRF
Primary location of system Database. If unset, (and PRVRF is unset) the Satellite will be administered locally .
PRVRF
Nulref
Old primary location (normally unset)
DEALAL
false
Indicates that ALL DBs are currently being deallocated from this location.
CURLOC
True current Location (available everywhere)
ADMLOC
Currently administered location (available everywhere).
PRMLOC
Primary location of its system db
DBPRIMARY
(ref array) - List of Databases primary at the current location.
LOCPRIMARY
(ref array) - List of Locations primary at the current location.
DBALL
List of Databases allocated to this location.
NoExtCreation
default false
If true, disables the creation of extracts by this location. Extract creation must be done by the Hub (or an authorised administering location)
LCpOvWrite
default false
If true, database files which are locked by dead users may be overwritten if an update requires an entire file copy.
Note: When a Global Project is created an initial Location element is created with a NAME of /PROJECTHUB and a LOCID of ‘HUB’. Its LINIT flag is set to TRUE. Note: Do not allow locked files in the current project to be overwritten during copying by Global updates if other projects are using the current project as a foreign one. This is because database readers in the other projects are valid users even though they are not recorded as users in the current project.
Administrator Command Reference Manual System and Global Projects
DBALL Element Attributes Lock
false
Owner
/name
LNKLI Element The LNKLI element contains a list of link elements LNK which specify the connections between pairs of Locations. Not used at this release. Attributes Name
/name
Type
LNKLI
Lock
false
Owner
/*GL
LNK Element Not used at this release. Attributes Name
/name
Description
unset
120 character text
LNKRX LINKRY LINKWV
GSTWLD Element Any existing stamps in the standard System database are copied to the Global Stamp World element and deleted from the System database.
Transaction Database This chapter is applicable to Global Projects only. The Global Daemon stores most of the commands that it is asked to perform in a transaction database. The System Administrator can use this database to get information about the progress of commands, and investigate why commands have failed. (Use GETWORK to see the latest changes to the transaction database) This chapter describes the structure of the transaction database, and explains the function of the elements within it, and their attributes. Note: To avoid data consistency errors, PDMS changes to the transaction database should not be made whilst the daemon is running. This includes deleting commands (TRINCOs) and merging the database. (Using Global Merging (syntax REMOTE MERGE) is OK.)
5.1
Structure of the Transaction Database The hierarchical structure of the transaction database is shown in Figure 5:1.: Structure of the Transaction Database. All the owner/child relations are one to many with the exception of TRMLST, TRFLST, and TRSLST. There is only one of each below an operation (TROPER) or output command (TROUCO) or an input command (TRINCO). There is no distinction between commands received from other locations (foreign) or from the local location as there are no fundamental differences between them. Whether they are local or foreign is determined by their position in the hierarchy and their owner’s names. The structure is a hierarchy leading to input commands received by the daemon, and the operations these have evaluated to.
TRMSGW Element The Transaction Message World element is called /*MS. There is only one such element and it contains elements that store the communication between the daemon, PDMS and other daemons. It owns any number of TRYEAR elements. Attributes NAME
Text
TRSETL
Logical Controls whether Local claim commands are stored
TRYEAR, TRMONT and TRDAY Elements These are organisation elements to allow the commands stored in the transaction database to be grouped by the date on which they were received. Each of these elements only has a single attribute NAME that is of the form: •
Name of %TRYEAR - year number. For example, /2001
•
Name of %TRMONT - as for year, then slash and month. For example, /2001/MAY
•
Name of %TRDAY - as for TRMONT, followed by slash then date. For example, /2001/ MAY/21
TRYEARs own TRMONTs, TRMONTs own TRDAYs and TRDAYs own TRUSERs.
5.4
TRUSER and TRLOC Elements These are further organisational elements under which commands are stored as issued by a specific user (TRUSER) and from a particular location (TRLOC). They each only have NAME attributes. A given transaction database will have a structure containing the TRDAY element for any date on which input commands were received. This will own a TRUSER element for each of the PDMS users that have issued daemon commands on that day. These will own a single TRLOC element with the name of the local location (e.g. CAM). There is only one TRLOC because the PDMS user only sends commands to the local daemon. The TRDAY may also own a TRUSER for the local and remote daemons (LOCALDAEMON and REMOTEDAEMON). These will own TROUCO commands received using RPC from other locations. These will own TRLOC elements for each location from which an input command has been received. LOCALDAEMON will own a TRLOC for the local location (e.g. CAM) since operations can send commands to the local site.The final system TRUSER element is named …/TIMEDUPDATES with a single TRLOC of the local site. This contains commands issued to process the regular timed updates.
5.5
TRINCO Element (Input Command) The TRINCO element stores the information about an input command issued to the daemon from a user, or another location’s daemon. The information includes the state of processing of the command and is sufficient for the command to be restarted when a daemon is
restarted, and is sufficient to generate the operations and output commands necessary to execute the command. Note: Local commands added from PDMS, that is those with TRLOCL True, do not contain successes, failures or messages. Attributes NAME
text
Not automatically generated
TRCNUM
int
Command number
INCSTA
int
The state of processing of the TRINCO
COMUID
ref
This is the reference of the command that sent this command to the daemon. For commands sent by this or other daemons it is the ref of the TROUCO element at the relevant location. For commands originating from PDMS it will be set to null.
TRMODU
int
Module number through with the USER has issued this command, or GLOBALDAEMON module
TRLOCL
log
True if command stored directly by PDMS independent of the Daemon
COMSTR
text
Command string USER entered that generate this command, else null
ORILOC[3]
text
Original Location where user issued the command
DESLOC3]
text
Ultimate target - destination location where command will be executed. For some commands this is the destination of subsidiary commands to be sent, not this command itself.
PRVLOC[3]
text
Previous Location which passed the command on to this location (normally the same as the TRLOC element)
AUXLOC[3]
text
Auxiliary location. Often used as a location to send auxiliary commands
SYSLOC[3]
text
Location of administrator when being remotely administered, else NULL
DEPCOU
int
number of other TRINCOs on which this is dependent (always zero)
DEPEND[*]
ref
References of TRINCOs on which it is dependent, (always none)
DEPTYP[*]
log
Type of dependencies - on success or failure
DATECR
date
Date command received and recreated
DATEAK
date
Date sent acknowledgement for command
NACKN
int
Number of times acknowledgement sent
EXTIME[4]
text
Time to execute command (hence allows a delay) -
DATERD
date
Date command made ready (after EXTIME has been reached)
Values of INCSTA State Attribute and Order of Change
5.6
RECEIVED
The command has been received ready for processing. DATECR is set.
ACKNOWLEDGED
An acknowledgement has been sent off by this daemon. DATEAK is set and NACKN incremented.
STALLED
The command has failed to create its operations and state will later return to ACKNOWLEDGED ready for retry, or to TIMEDOUT.
READY
The command has reached its execute time and is independent. DATERD is set.
COMPLETE
The command has been processed, and results obtained. DATECM is set.
REPLIED
The daemon has sent the results back to the originating location. DATERP is set and NREPLY incremented.
PROCESSED
An acknowledgement for the result received from originating location. DATEND is set and NREPAK incremented.
REDUNDANT
The command will not be executed now due to dependency rules. DATEND is set.
CANCELLED
The command has been cancelled and finished with TRPASS false. DATEND is set.
TIMEDOUT
The command has timed out before creating its operations and finished with TRPASS false. DATEND is set.
TROUCO Element (Output Command) The TROUCO element contains information about an output command to be issued by the daemon to itself, or to the daemon at another location. The information includes the state of processing of the command and is sufficient for the command to be resent when a daemon is restarted. Output commands are generated by an input command when operations are created. They may be destined to be executed at this, or another site.
Ref of the TRINCO of this command stored in the receiving location transaction database. This is NULL until an acknowledgement is received.
ORILOC[3]
text
Original Location where user issued the command.
DESLOC3]
text
Ultimate target - destination location where command will be executed. For some commands this is the destination of subsidiary commands to be sent, not this command itself.
PRVLOC[3]
text
Previous Location which passed the command on to this location (normally the same as the TRLOC element).
AUXLOC[3]
text
Auxiliary location. Often used as a location to send auxiliary commands.
SYSLOC[3]
text
Location of administrator when being remotely administered, else NULL.
NXTARL[3]-
text
Next Target location - this is needed to determine which port to assign the output command to, and which location to send the command.
DEPCOU
int
Number of other TROPERs and TROUCOs on which this is dependent.
DEPEND[*]
ref
References of TROPERs and TROUCOs on which it is dependent.
DEPTYP[*]
log
Type of dependencies - on success or failure.
PREOP
ref
Reference of previous operation which generated this output command as one of its post operations. If no previous operation this is NULL.
DATECR
date
Date command created by owning input command.
DATERD
date
Date command is ready to send after dependencies satisfied.
DATESN
date
Date command sent to destination location.
NRETRY
int
Number of attempts when command was sent.
MAXTRY
int
Number of attempts sending command before command fails.
WAITIM
int
Number of seconds delay between attempts at sending.
ENDTIM
date
Date when command will fail if sending remains stalled.
DATEAK
date
Date acknowledgement received from destination location
Values of OUTSTA State Attribute and Order of Change
5.7
WAIT
The command is waiting until it is independent of any other operation/command. DATECR is set.
READY
The command is independent and ready to be sent. DATERD is set.
STALLED
The command could not be sent. State will later return to ACKNOWLEDGED ready for retry, or to TIMEDOUT.
SENT
The command has been sent acknowledgement. DATESN is incremented.
ACKNOWLEDGED
An acknowledgement has been received from the destination location. DATEAK is set, NACKN is incremented, CMREF is set.
REPLIED
A reply with results has been received from the destination location. DATERP is set, NREPLY is incremented.
COMPLETE
A reply acknowledgement has been returned to the executing location. DATERK, TRPASS, MSTEXT are set. NREPAK is incremented.
STALLED_POSTOP
Post operations could not be created. State will later return to COMPLETE ready for retry, or to TIMEDOUT.
PROCESSED
Any required post operations have been generated using the result of this command. DATEND is set.
REDUNDANT
The command will not be executed now due to dependency rules. DATEND is set.
CANCELLED
The command has been cancelled by owning TRINCO by a user. DATEND is set.
TIMEDOUT
The command has had the number of sends exhausted, or maximum time exceeded. DATEND is set.
and waits for set, NRETRY
an is
TROPER Element (Operation) The TROPER element stores the information about an operation to be executed by the daemon. The information includes the state of processing of the operation and is sufficient for the operation to execute when a daemon is restarted. Operations are generated by an input command when operations and output commands are created.
Values of OPSTAT State Attribute and Order of Change
5.8
WAIT
The operation is waiting until it is independent of any other operation/command. DATECR is set.
READY
The operation is independent and ready to execute. DATERD is set.
STALLED
The operation could not be executed. State will later return to READY (ready for retry), or to TIMEDOUT. DATESL is set.
RUNNING
The command has started running. DATERN is set, NRETRY is incremented.
COMPLETE
A reply acknowledgement has been returned to the executing location. DATECM, TRPASS, MSTEXT are set.
STALLED_POSTOP
Post operations could not be created. State will later return to COMPLETE ready for retry, or to TIMEDOUT.
PROCESSED
Any required post operations have been generated using the result of this command. DATEND is set.
REDUNDANT
The command will not be executed now due to dependency rules. DATEND is set.
CANCELLED
The command has been cancelled by owning TRINCO by a user. DATEND is set.
TIMEDOUT
The command has had the number of sends exhausted, or maximum time exceeded. DATEND is set.
TRMLST, TRSLST, and TRFLST Elements The TRMLST, TRSLST, and TRFLST elements are organisational elements (Message Lists, Success Lists and Failure Lists respectively): •
Messages (TRMESS) are grouped under Message Lists (TRMLST).
•
Successes (TRSUCC) are grouped under Success Lists (TRSLST) and TRMLST.
•
Failures (TRFAIL) are grouped under Failure Lists (TRFLST) and TRMLST.
Failures and Successes are propagated back to the originating location as messages as soon as they are generated and before the full result is handed back. These are finally stored under TRMLST as TRSUCC and TRFAIL elements. All the list elements have no user attributes.
5.9
TRMESS, TRSUCC, and TRFAIL Elements The TRMESS, TRSUCC, and TRFAIL elements are for Messages, Successes and Failures respectively. Operations and Output Commands are able to have any number of messages attached to them. They will be generated by Local operation during their execution and be stored. Remote operations will receive messages from their output commands that will:
generate messages relating to transaction events (sends, acknowledgements etc.)
•
receive messages from the execution of commands at other site
•
receive transaction event messages forwarded through other site remote operations.
Operations and output commands have a TRSUCC attribute stating a success or (relative) failure. Each point of failure will generate a single TRFAIL element (e.g. failure to claim an element). Each point of success will generate a single TRSUCC element (E.g. an element claimed). The attributes of TRSUCC and TRFAIL elements are equivalent. They include: •
A Reference to an element involved in the operation (e.g. the ref of a claimed element)
•
A double integer code relating to a PDMS message or error (0,0 if not known or relevant)
•
A text string which is a representation of the said message or error.
•
An integer qualifier to be used for such things as session numbers etc.
The result of a command (TROUCO) is the sum of all TRSUCC and TRFAIL elements owned by its operations and output commands. All of these are communicated back to either the user (if it is a local command) or propagated to the originating site (if it is a foreign command). In the latter case the compounded errors will appear under the relevant originating TROUCO operation and hence onwards and upwards Whether a TROPER itself is classed as a success is determined by its execute method. Input Commands are successes if all its operations AND output commands are successes. An output Command is a success if the input command it spawned returns a success. Results are only passed on to the generating TROUCO when the input command is totally finished. Messages are sent immediately they are generated before waiting for operation or command conclusion. They go the same route as the result, being compounded by a TROUCO and transmitted to other site TROPER elements. They are only stored under the final TRINCO generated from a USER command. Attributes for Elements %TRSUCC and %TRFAIL DATEMS
date
Date success/failure raised.
MESNUM[2]
int[2]
Message/error number relating to MSTEXT or 0,0 if none available. This can be used as an indication of the severity of a failure.
MSTEXT
text
Any result text (not passed on).
MSTYPE
int
Data type indicates significance of MESQUA, MSREF, MSDTXT.
MESQUA
int
Data qualifier.
MESREF
ref
Data refno corresponding to the error.
MSDTXT
text
Data text of the result/error.
MSLOC
text
Name of location that generated the success/failure
TRCNUM
int
Source command type number (if generated by a TRINCO).
Source operation type number (if generated by a TROPER).
TRTYPE
text
Pseudo-attribute, which combines the OPTYPE (Operation Number) and COMMTYPE (Command Number) attributes. Allows you to query the member operations of a command independently of whether the operations are TROUCO or TROPER. It combines the TRCNUM and TRONUM queries (these are attributes of TROUCO and TROPER respectively).
Attributes for Element %TRMESS DATEMS
Date
Date success/failure raised.
MESNUM[2]
int[2]
Message/error number relating to MSTEXT or 0,0 if none available.
MSTEXT
Text
Message text.
MSLOC
text
Name of location that generated the success/failure.
MSSENT
log
Unused.
TRCNUM
int
Source command type number (if generated by a TRINCO).
TRONUM
int
Source operation type number (if generated by a TROPER).
TRTYPE
text
Pseudo-attribute, which combines the OPTYPE (Operation Number) and COMMTYPE (Command Number) attributes.
Command Summary This chapter lists the ADMIN commands in functional groups. Details of the commands are given in Command Details in alphabetical order of command name.
6.1
Project Definition ACCESS
Changes the access rights of the specified user to PDMS modules.
ACRADD
Adds a named ACR to the current ACR Group.
ACRREM
Removes a named ACR from the current ACR Group.
ADD
Places a named DB at a specified position in the current MDB list.
AUTHENTICATION
Switches authentication user on/off.
AUTHUSERREM/OVE
Removes authenticated user.
CHANGE
Changes database access type, and the claim mode for multiwrite databases. (In a Global project, also changes primary location)
CDESC
Changes the description of the specified user, team, database or MDB.
CNAME
Changes the name of the specified user, team, DB or MDB.
COPY
Copies a DB, MDB, Team, User, Module or Stamp.
CREATE
Creates a DB (including Extract DBs), MDB, Team, User, Windows NT Authenticated user or Module.
CURRENT
Moves a DB to a specified position in the current MDB list.
Command Details The commands are described in this chapter in alphabetical order of command names. The descriptions are usually under subheadings of Function, Description, Examples, Command Syntax, and Related Commands. The syntax of commands is shown by syntax graphs. These are discussed in the first two sections. The third section contains the command descriptions.
7.1
Conventions Used in the Syntax Graphs The syntax graph conventions are as follows: •
Commands are shown in a combination of uppercase and lowercase letters, where the capital letters indicate the minimum abbreviation.
Note: This convention does not mean that the second part of the command must be typed in lowercase letters; commands may be entered in any combination of uppercase and lowercase letters. •
For example, the command
CReate •
can be input in any of the following forms:
CR CRE CREA CREAT CREATE •
Commands shown in all uppercase letters cannot be abbreviated.
•
Command arguments are shown in lowercase letters. These are just descriptions of what you need to enter. For example:
FONTDirectory name •
means that to set the name of the Font Directory to newfonts, you enter:
FONTD newfonts •
Syntax graphs are read from top left to bottom right. The start point is shown by >, and you can follow any path through the graph until the exit point, shown by >, is reached.
Points marked with a plus sign (+) are option junctions which allow you to input any one of the commands to the right of the junction. For example: >----+--- ABC ------. | | |--- PQR ------| | | ‘--------------+--->
•
means you can type in ABC or PQR or just press Enter to get the default option.
•
Text in angle brackets <. . . > is the name of another syntax graph. This convention is used for syntax which occurs in many places. The graphs referred to are described at the end of this section. For example: >----+--- ABC ------. | | |--- PQR ------| | | |--- ----| | | ‘--------------+--->
•
means you can type in ABC or PQR or any command allowed by the syntax given in diagram or just press Enter to get the default option.
•
Points marked with an asterisk (*) are loop back junctions. Command options following these may be repeated as required. For example: .-----<-------. / | >---*--- option1 ---| | | |--- option2 ---| | | ‘--- option3 ---+--->
•
means that you can enter any combination of option1 and/or option2 and/or option3, where the options can be commands, other syntax diagrams, or command arguments.
•
The simplified format: .----<------. / | >---*--- name ----+--->
•
means that you may type in a list of PDMS names, separated by at least one space.
Notes on Syntax Graphs When a Location needs to be specified, it is shown as in the syntax graphs. It can be: •
A three-letter Word. For example: CAM, the LOCID of a LOC element, where the LOCID is 3 capital letters.
•
A text string of three alphanumeric characters, beginning with a letter. For example: 'CAM’, ‘A99' or ‘abc’, the LOCID of a LOC element.
•
A PDMS general identifier which points to a LOC element. For example: / LOCATION_AAA.
<when> >--+-- BEFORE --. | | ‘-- AFTER ---+------ --------. | | |------ SESS n --------| | | ‘-- STAMP stampname ---+--->
>--- time --- day --- month --- year time is in the format hh:mm where hhx is the hour and mm the minutes. If not given then the default of 23:59 is taken. There must not be any spaces around the colon. day will be an integer. If not specified, the current day is taken. The day must be given if no time was specified. month can be entered as a word, or as a number separated by a slash. If not given the current month is assumed. If used, the slash must be surrounded by spaces. year will default to the current year. It may be entered as two or four figures. Examples:
12:00 21 January 2002 9:30 11 / 1 / 02 10:30 21 / 1 / 2002 21 January
7.3
Detailed Descriptions of Commands The detailed descriptions appear on the following pages in alphabetical order of command name. Each description starts on a new page. The command name and relevant functional group are at the top of the first page of the description, and the command name is repeated on each continuation page.
When a command is associated with the Global Project Administration functional group, the command is specific to Global projects. Commands associated with other functional groups may be used for Standard and Global projects, and any particular aspect of a command that concerns Global projects is highlighted by the appearance of 'Global' in larger typeface.
7.3.1
ACCESS (Project definition) Function: Changes the access rights of the specified user to PDMS modules. Example:
ACCESS ADMINUSER FREE DRAFTUSER GEN Give user ADMINUSER FREE access, user DRAFTUSER GENERAL access. Command Syntax: .-------------<-------------. / | >--- ACcess --*-- userid ---*--- FRee ------| | | ‘--- GEneral ---+--->
Related Commands:
CREATE
7.3.2
ACRADD (Project definition) Function: Adds an ACR to an ACR Group. Description: The ACR and the ACR Group must already exist, and the ACR Group must be the current element. You can then give a list of ACR names to be added to the Group. Note that ACR Groups cannot contain other ACR Groups. Examples:
ACRADD /ACR1 /ACR22 /ACR24 Adds the ACRs /ACR1, /ACR22 and /ACR24 to the current ACR Group.
ACRREM (Project definition) Function: Removes an ACR from an ACR Group. Description: The ACR Group must be the current element. You can then give a list of ACR names to be removed from the Group. Examples:
ACRREM /ACR1 /ACR22 /ACR24 Removes the ACRs /ACR1, /ACR22 and /ACR24 from the current ACR Group Command Syntax:
ADD (Project definition) Function: Places a named DB at a specified position in the current MDB list. Description: The list position must be in the range 1 through 1000. If no list position is specified, the specified DB is added as a deferred database (equivalent to DEFER). Examples:
ADD STEELN/STEELN 1 Place DB STEELN STEELN at the head of the current MDB list
Related Commands: REMOVE, DEFER, CURRENT, EXCHANGEREMOVE, DEFER, CURRENT, EXCHANGE
7.3.5
ADMINISTER (Global Project Administration - Remote Administration) Function: Creates or opens a system database to allow you to administer a remote location. Description: Before you can use this command: •
The Location must have been created using the NEW LOC command, and its Location identifier must have been set. For example: Locid 'AAA' •
The system database of the new Location must be made Primary at the administering Location using the SYSTEMLOCATION command. For example:
SYSTEMLOC /AAA PRIMARY AT /BBB where /AAA is the identifier of the new Location, and /BBB is the identifier of the Administering Location, that is, the location where the System database for the Location will be Primary. The NEWSYSTEM option is only available at the Hub. It creates a system database for a new location in the transfer area. (This is similar to the GENERATE LOCATION command.) The system database created is a copy of the Hub system database without MDBs and with only a SYSTEM user. The Administrator at the Hub can then create Users and MDBs (as well as Teams and Databases) for the Location before it is set up. The SYSTEM option is available at the Administering Location, that is, the location where the System database for the Location is Primary. This may be the Hub or another Satellite. This command will close the local system database and open the appropriate satellite system database. The database will be opened with Write access unless the READONLY keyword is used. After the SYSTEM or NEWSYSTEM commands have been given, you will be able to carry out administration tasks for the remote location. To return to administering your own (current) Location, give the command ADMINISTER LOCAL. To return to administering the last system database which was open, give the command ADMINISTER SAME. Any location may issue an ADMINISTER command for another other location’s system database. If the system database is not Primary, then the system database will be opened READONLY.
Once you have selected a remote system database, you can give most ADMIN commands, which will operate on the remote Location. In particular, the following commands can be used for housekeeping tasks on the remote System Database:
EXPUNGE SYSTEM MERGE CHANGES SYSTEM CHECK SYSTEM RECONFIGURE SYSTEM The Hub will not be allowed to REPLICATE the project when it is administering a remote location, since the wrong system database will be replicated. However REPLICATE SYSTEM commands (which generate macros to replicate the project structure) will still be valid. The administered location will still be able to lock or isolate the project locally. It will also be able to administer its primary constructor databases by using the REMOTE command, where is its own location identifier, followed by one of the normal commands:
EXPUNGE BACKTRACK MERGE CHANGES REVERT CHECK Reconfiguration will also be possible provided that suitable databases are primary at the location. Examples:
ADMINISTER NEWSYSTEM /Cambridge ADMINISTER NEWSYSTEM 'CAM' Allows the Hub Administrator to create data (Users, MDBs etc) for a Location in the transfer directory.
ADMINISTER SYSTEM /Cambridge ADMINISTER SYSTEM 'CAM' Allows any System Administrator to read the System Database for Cambridge. Only the Administrator at the Location where the Cambridge System Database is Primary will have write access to it.
ADMINISTER SYSTEM SAME Allows a System Administrator who is administering other Locations to open the last System database opened.
ADMINISTER SYSTEM LOCAL Allows a System Administrator who is administering other Locations to open the local System database.
ADMINISTER SYSTEM AT /Cambridge ADMINISTER SYSTEM LOCAL READONLY This is equivalent to entering the ADMIN module as ADMIN READONLY.
Command Syntax: >-- ADMINISTER --+--- NEWSYSTEM -----------------------------. | | ‘--- SYSTEM ------+-- AT ---. | | | | |--- SAME -------| | | | | ‘--- LOCAL ------+--- READONLY --| | | ‘---------------+--->
Querying:
7.3.6
>--- Q CURLOC --->
Returns the true current location
>--- Q ADMLOC --->
Returns the currently administered location
ALLOCATE (Global Project Administration - Hub only) Function: Allocates databases and copies them to a Location. Description: Each Location has a list of databases that are allocated to it. The ALLOCATE command adds a database to this list. A named database or all databases can be specified. The allocation can be deferred until a given time. The databases must already exist at the Hub. The Hub sends its own copy of the database, or that of the Location’s parent, to the Location. This is not necessarily the most up-to-date copy. Note that the Database will also be allocated to all ancestors of the Location, if it is not already allocated to them. When a DRAFT Database is allocated, the picture files are not automatically copied with it. They will arrive with the next update. By default, the allocated databases will be Secondary, but you can specify that they will be Primary. If a database already exists at a location, you can change its Primary/Secondary status using the CHANGE command. Several Databases can be allocated in the same operation using the ALLOCATE command. In order for an extract database to be used at a satellite, all owning extracts must also have been allocated there. Offline Locations The ALLOCATE PRIMARY option cannot be used. Use ALLOCATE followed by CHANGE PRIMARY. The date option is not allowed. Note that ALLOCATE should be followed by a TRANSFER command to copy the database to the location. The CHANGE PRIMARY command should not be issued until this has been done. Using Macros to Allocate Databases You will probably use a macro for long lists of databases allocations, for example, when a project is first set up.
The allocation process may take some time if there is a slow link between Hub and Satellite and/or if databases sizes are large. Note that if a de-allocation is in progress, then the allocation will stall until the de-allocation is complete before commencing. Make sure that you do not try to allocate a database to the same location twice. If the allocation appears to have failed, check the transaction databases at both the Hub and the Satellite before attempting to repeat the command. To check that the allocation has been successful, GETWORK and then navigate to the LOC element. Navigate to its DBALL (allocation list) member, and query its members. Wait until the DBALL element at both the Hub and the Satellite lists all the allocated databases before continuing. Note: If the transaction database for a location is being allocated, this command is not recorded in the transaction database. It is not normally necessary to allocate it or change its primary location explicitly. Note: The OVERRIDE PROPG option cannot be used with a deferred time. Examples:
ALLOCATE PIPE/PIPE PRIMARY AT CAM Copies database PIPE/PIPE from the current Location to Location CAM, making it Primary.
ALLOCATE ALL AT LON AT 23:30 Copies all databases which exist at the current Location but do not exist at Location LON, from the current Location to Location LON, at 2330 hrs. The Primary/Secondary status will not be changed.
ALLOCATE ALL AT OXF OVERRIDE PROPG Copies all databases, including non-propagating databases, which exist at the current Location but do not exist at Location OXF, from the current Location to Location OXF. The Primary/Secondary status will not be changed. Transaction databases will not actually be copied, but empty database files will be created at secondary locations. This command is useful when changing the Hub location, since it ensures that the DB allocation lists of the old and new Hub locations match. Command Syntax: >-ALLOCate -+- teamid -. | | |----------+- dbname -+-------------. | | | | |- PRIMary ---| | | | | ‘- SECOndary -+-AT loc-+-AT