How To Read And Write Data

Introduction

The MDSplus API (applications programming interface) consists of a small number of simple calls. The basic calls as they would be ordered in an application are:

mdsconnect,'server_name'

   mdsopen,'tree_name',shot_number

     result= mdsvalue('expression')

     mdsput,'node_name','expression'

   mdsclose,[tree_name,shot]

mdsdisconnect

Details of the syntax will be, to some extent, language specific. At the end of this section you will find links with more information and examples.

Connecting and Disconnecting to Servers''''

MDSplus operates under the client/server model. The commands mdsconnect and mdsdisconnect are used to control which MDSplus server is being used. In a typical installation, many users will access data from computers on the same local area network (LAN) as the MDSplus file server. For these users, the disks and directories with data may be configured to appear as local disks on the users systems. In this case, which we can call LOCAL access, each user's system will be running its own MDSplus server and handling expression evaluation, data compression and decompression and so forth. In other cases, the files will be on remote systems to which the user does not have direct file access. In this situation, which we will call REMOTE access, the local system will run an MDSplus client. For operation in this mode, the MDSplus commands in an application must be preceeded by a command to connect to a particular server.

Opening and Closing trees

While some TDI expressions can be evaluated without any reference to MDSplus trees, in almost all cases a user will want to have a particular tree (or trees) open for data access. The commands mdsopen and mdsclose carry out this function. mdsopen takes a tree name and shot number as arguments. Up to eight trees may be open at once. A stack is maintained and subsequent commands refer to the most recently opened tree. With the same tree name and shot number arguments, mdsclose will close specific trees (and pop the stack as appropriate.) Without arguments, mdsclose will close all open trees.

Reading Data - Evaluating Expressions

Data is read from trees with the mdsvalue call. This call evaluates a TDI expression and returns the result. In many cases the expression will simply be the name of a node in the data hierarchy. Simple TDI functions allow the components of composite data types, like signals to be returned.

Expressions may also be stored in nodes of a tree. When these nodes are referenced, the expressions are evaluated returning the results of the TDI commands. This feature can be used to give users transparent access to data which is processed as the commands are issued rather than calculated ahead of time and stored. For example raw data can be corrected for offsets and calibrations (all of which are stored in the trees) providing users with calibrated data without storing essentially redundant information. Further, if the calibrations were to be corrected, they would apply automatically whenever the data were accessed. A common source of error is confusion over whether the actual data or the expression that defines it are being used and some care must be taken.

Writing data

Data is written into trees with the mdsput command. This command takes two principal arguments; the first specifies which node is being written to and the second is the data which will be put into that node. In many cases, efficiencies or consistency can be obtained by writing expressions rather than numeric data. Uniform time bases can be efficiently represented by a composite variable containing the offset, delta time and number of samples. See the users guide for details.

Status codes

Most MDSplus commands return optional status codes. Success or failure is indicated by the lowest bit. That is, odd numbered status codes denote success and even ones denote failure. The command mdsgetmsg(status_code) will return a text string containing the actual error message.

Fortran Language Details

C Language Details and more C examples

IDL Language Details

Matlab Language Details

next page