This is the third in a short series of posts that explain Project Database Unique IDs (PDUIDs). This post explains how PDUIDs can be used in Cradle. The next and final post in the series will explain how PDUIDs can be controlled when information is moved between databases.
Opening Items
You can open an item by simply specifying its PDUID. You do not need to specify the type of the item using the Item Type Chooser dialogs in the WorkBench and web UIs. For items in models, you do not need to choose the correct domain and then locate the model inside that domain.
You simply specify the PDUID:
The latest instance of the item will be opened.
Queries
You can find items based on their PDUIDs, or components of the PDUIDs, in addition to any other criteria that you may have set inside the query. Select the PUIDs tab in the Query Details dialog:
The selection of items by PDUID will return all instances that you can access RO or RW.
Specific PID
If you choose Specific PID then you can enter a PID and an optional UID range. If you only enter a PID, then the query will return all items whose PDUIDs contain that PID. This could be useful if you have been importing data from other databases and so the items in your database have PDUIDs with different PIDs.
For example, if you have separate databases that have different PIDs for:
- Different missions in a programme, or
- Different vessels in a class of vessels
and you have combined the data from several of these databases into one database, then this option will allow you to find only the items with a single PID, such as for a single mission or for a single vessel. You can optionally filter the items further by specifying a UID range. You can omit the leading zeroes from the UIDs.
Specific PUID
If you choose Specific PUID then you can enter a PUID (the PID and UID) and the query will return all instances of the item with that specific PUID that you can access RO or RW and subject to the other constraints in the query (such as returning only the latest instance that you may have specified in the ID tab).
PUID From
If you choose PUID from then you can enter a PUID (the PID and UID) and the query will return all instances of all items whose PUIDs are greater than the value you specified which will be the combination of:
- All items with the same PID and whose UIDs are greater than your specified value
- All items with PIDs greater than your specified value and any UID
that you can access RO or RW and subject to the other constraints in the query (such as returning only the latest instance that you may have set in the ID tab).
Referencing Data in Other Items
Items in a Cradle database can hold their information in any number of frames. Each frame is of a user-defined frame type that defines the characteristics of the frame. The data in frames of a frame type is normally stored in the Cradle database, but this can be controlled by the storage mechanism of the frame’s frame type:
| In PDB | : | The frame’s data is stored in the Cradle database |
| As File | : | The frame’s data is stored in an external file whose pathname, size, last access and modified times are stored in the Cradle database |
| By Command | : | The frame’s data is held in an external environment under an identity, the database stores this identity, and uses Get and Set commands in the frame type to move the data between the environment (specified by the $IDENTITY Command Directive) and a temporary file (specified by the $PATH Command Directive) where it can be operated on. For example: Get: {unix cp}{win copy} “$PATH” “$IDENTITY” This example exports the frame’s contents and sends to the application supplied in the frame type’s View or Edit command and saves the contents from the application back into the frame. |
| As Reference | : | The frame’s data is stored at a location outside Cradle and the frame stores this external location (such as a pathname or a URL). The data’s location is given to the frame type’s View command, which does not wait for this processing to complete – unlike in the other storage mechanisms. |
| Referenced File From Item | : | The frame’s data is held in a frame of a different item. The frame stores the PDUID of the other item whose data is being referenced (latest instance), and the name of the frame in this other item that contains the data. When the frame is accessed via a View command, Cradle opens the other item using its PDUID and copies the data from the referenced frame into a temporary file. This mechanism allows data in one item to reference data in another item, sharing the data between them. |
Cradle URLs
Cradle URLs are URLs that can start a Cradle WorkBench client and either open an item or run a query. The action specified in a Cradle URL is executed by the c_url utility shipped in the Cradle clients. It can be run from a command line, an application, or a web browser that has been told about Cradle URLs (an option when Cradle clients are installed).
Cradle URLs are a way for another application to interface to Cradle. The other application can store Cradle URLs as, in effect, pointers to items in the Cradle database. When the user wants to access the Cradle item, the external application can either run c_url on the specified Cradle URL, or route it through a web browser that, in turn, will launch c_url.
Cradle URI Scheme
A URI scheme defines the structure of a URL. The Cradle URI scheme is:
cradle:[username][:password][;AUTH=authentication]@project[:access][?action¶ms…]
by specifying a Cradle URL with the PDUID and instance details of the item to be opened.
Creating Cradle URLs
Cradle URLs can be created from the Tools tab WorkBench UI or any web UI. Once an item is selected:
The Cradle URL shown in the dialog can be copied and pasted:
- Into another application to provide a link to the selected item in Cradle
- Into the c_url utility to execute the action in the URL
- Into a web browser that understands the Cradle scheme, when it will launch the c_url utility to perform the requested action
API
Cradle has an Application Programming Interface (API) that supports both C/C++ and VB.NET. You can create any number of applications using the API. All of these applications will connect to the CDS in the same way as any non-web-based Cradle client supplied by 3SL (such as WorkBench or Document Publisher). Each of your applications can service one or many users. You need one API/WSI connection licence for every application that you want to concurrently connect to Cradle.
The API contains many routines. Collectively these routines provide facilities to create, read, update and delete both items and the cross references between them. The main data type for items is CAPI_ITEM_T which has components for both item identities and PDUIDs. The main data type for cross references is CAPI_XREF_T which contains the details of the cross reference but not the items that it connects. This is because cross references are not retrieved by themselves, rather the API returns a list of linked items each of which is a structure containing the CAPI_ITEM_T for the linked item and the CAPI_XREF_T for the cross reference by which it is linked. As such, the “from” and “to” items for a cross reference are implicit in the data structures.
A PDUID can be used to open an existing item using CAPI_Item_Open().
WSI
Cradle has a Web Services Interface (WSI) that supports a RESTful message protocol. You can create any number of applications using the WSI. All of these applications will connect to the Cradle Web Server (CWS) in the same way as any web-based Cradle client supplied by 3SL. Each of your applications can service one or many users. You need one API/WSI connection licence for every application that you want to concurrently connect to Cradle. Each of these connections can either be session-based or it can use message-by-message connections.
The WSI contains many operations. Collectively, these operations provide facilities to create, read, update and delete both items and the cross references between items. The data sent and received in these operations is packaged in JSON. These JSON packets contain full details of items and cross references and include both item identities and PDUIDs.
The WSI predominately uses PDUIDs as a means to specify items of information, and for links between items. For example using the curl command to send a HTTP message to a Cradle WSI session whose details are in the file cookies.txt to the CWS running on port 8015 at server myserver to get the contents of a database item into a local JSON file:
curl -X GET -b cookies.txt “http://myserver:8015/rest/projects/DEMO/items/16EC668D4ADEMO010000000907?fields=all” > myItem.json
and to update the same item in Cradle with new information added into the same local JSON file:
curl -X PUT -b cookies.txt “http://myserver:8015/rest/projects/DEMO/items/16EC668D4ADEMO010000000907” -d @myItem.json